X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/882678ebb43804d34d20ba8781647fe136ae67d9..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index cb6031ae97..e8e54c4526 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -3,9 +3,106 @@ // Purpose: interface of wxDC // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + Logical raster operations which can be used with wxDC::SetLogicalFunction + and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit). + + The description of the values below refer to how a generic @e src source pixel + and the corresponding @e dst destination pixel gets combined together to produce + the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source + and the destination pixel and always put zeroes or ones in the final surface. +*/ +enum wxRasterOperationMode +{ + wxCLEAR, //!< 0 + wxXOR, //!< @e src XOR @e dst + wxINVERT, //!< NOT @e dst + wxOR_REVERSE, //!< @e src OR (NOT @e dst) + wxAND_REVERSE, //!< @e src AND (NOT @e dst) + wxCOPY, //!< @e src + wxAND, //!< @e src AND @e dst + wxAND_INVERT, //!< (NOT @e src) AND @e dst + wxNO_OP, //!< @e dst + wxNOR, //!< (NOT @e src) AND (NOT @e dst) + wxEQUIV, //!< (NOT @e src) XOR @e dst + wxSRC_INVERT, //!< (NOT @e src) + wxOR_INVERT, //!< (NOT @e src) OR @e dst + wxNAND, //!< (NOT @e src) OR (NOT @e dst) + wxOR, //!< @e src OR @e dst + wxSET //!< 1 +}; + +/** + Flood styles used by wxDC::FloodFill. +*/ +enum wxFloodFillStyle +{ + /** The flooding occurs until a colour other than the given colour is encountered. */ + wxFLOOD_SURFACE = 1, + + /** The area to be flooded is bounded by the given colour. */ + wxFLOOD_BORDER +}; + +/** + The mapping used to transform @e logical units to @e device units. + See wxDC::SetMapMode. +*/ +enum wxMappingMode +{ + /** + 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, + + /** + 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_TWIPS, + + /** + Each logical unit is a @e "printer point" i.e. 1/72 of an inch. + Equivalent to about 353 micrometers. + */ + 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". +}; + + /** @class wxDC @@ -16,7 +113,7 @@ 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 @@ -37,9 +134,45 @@ wxDCImpl class. The user-visible classes such as wxClientDC and wxPaintDC merely forward all calls to the backend implementation. - 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. + + @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 explicitly + 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. + + + @section dc_alpha_support Support for Transparency / Alpha Channel + + 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} @category{dc,gdi} @@ -50,143 +183,97 @@ @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 { public: /** - Copy from a source DC to this DC, specifying the destination - coordinates, size of area to copy, source DC, source coordinates, - logical function, whether to use a bitmap mask, and mask source - position. - - @param xdest - Destination device context x position. - @param ydest - Destination device context y position. - @param width - Width of source area to be copied. - @param height - Height of source area to be copied. - @param source - Source device context. - @param xsrc - Source device context x position. - @param ysrc - Source device context y position. - @param logicalFunc - Logical function to use, see SetLogicalFunction(). - @param useMask - If @true, Blit does a transparent blit using the mask that is - associated with the bitmap selected into the source device context. - The Windows implementation does the following if MaskBlt cannot be - used: -
    -
  1. Creates a temporary bitmap and copies the destination area into - it.
  2. -
  3. Copies the source area into the temporary bitmap using the - specified logical function.
  4. -
  5. Sets the masked area in the temporary bitmap to BLACK by ANDing - the mask bitmap with the temp bitmap with the foreground colour - set to WHITE and the bg colour set to BLACK.
  6. -
  7. Sets the unmasked area in the destination area to BLACK by - ANDing the mask bitmap with the destination area with the - foreground colour set to BLACK and the background colour set to - WHITE.
  8. -
  9. ORs the temporary bitmap with the destination area.
  10. -
  11. Deletes the temporary bitmap.
  12. -
- 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 - 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. - @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are - @c -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are - @c -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - - @remarks There is partial support for Blit() in wxPostScriptDC, under X. - - @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask + @name Coordinate conversion functions */ - bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, - wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, - wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, - wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); + //@{ /** - Adds the specified point to the bounding box which can be retrieved - with MinX(), MaxX() and MinY(), MaxY() functions. - - @see ResetBoundingBox() + Convert @e device X coordinate to logical coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. */ - void CalcBoundingBox(wxCoord x, wxCoord y); + wxCoord DeviceToLogicalX(wxCoord x) const; /** - Clears the device context using the current background brush. + 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. */ - void Clear(); + wxCoord DeviceToLogicalXRel(wxCoord x) const; /** - Displays a cross hair using the current pen. This is a vertical and - horizontal line the height and width of the window, centred on the - given point. + Converts @e device Y coordinate to logical coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. */ - void CrossHair(wxCoord x, wxCoord y); + wxCoord DeviceToLogicalY(wxCoord y) const; /** - Destroys the current clipping region so that none of the DC is clipped. - - @see SetClippingRegion() + 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. */ - void DestroyClippingRegion(); + wxCoord DeviceToLogicalYRel(wxCoord y) const; /** - Convert device X coordinate to logical coordinate, using the current + Converts logical X coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. */ - wxCoord DeviceToLogicalX(wxCoord x) const; + wxCoord LogicalToDeviceX(wxCoord x) const; /** - Convert device X coordinate to relative logical coordinate, using the + Converts logical X coordinate to relative device 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; + wxCoord LogicalToDeviceXRel(wxCoord x) const; /** - Converts device Y coordinate to logical coordinate, using the current + Converts logical Y coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation. */ - wxCoord DeviceToLogicalY(wxCoord y) const; + wxCoord LogicalToDeviceY(wxCoord y) const; /** - Convert device Y coordinate to relative logical coordinate, using the + Converts logical Y coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation. Use this for converting a height, for example. */ - wxCoord DeviceToLogicalYRel(wxCoord y) const; + wxCoord LogicalToDeviceYRel(wxCoord y) const; + + //@} + + + + /** + @name Drawing functions + */ + //@{ + + /** + Clears the device context using the current background brush. + */ + void Clear(); /** Draws an arc of a circle, centred on (@a xc, @a yc), with starting - point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is - used for the outline and the current brush for filling the shape. + point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd). + The current pen is used for the outline and the current brush for + filling the shape. The arc is drawn in a counter-clockwise direction from the start point to the end point. */ - void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord xc, wxCoord yc); + void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd, + wxCoord xc, wxCoord yc); + + /** + @overload + */ + void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre); /** Draw a bitmap on the device context at the specified point. If @@ -203,25 +290,34 @@ public: void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, bool useMask = false); - //@{ + /** + @overload + */ + void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, + bool useMask = false); + /** Draws a check mark inside the given rectangle. */ void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + @overload + */ void DrawCheckMark(const wxRect& rect); - //@} - //@{ /** Draws a circle with the given centre and radius. @see DrawEllipse() */ void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + + /** + @overload + */ void DrawCircle(const wxPoint& pt, wxCoord radius); - //@} - //@{ /** Draws an ellipse contained in the rectangle specified either with the given top left corner and the given size or directly. The current pen @@ -230,9 +326,16 @@ public: @see DrawCircle() */ void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + @overload + */ void DrawEllipse(const wxPoint& pt, const wxSize& size); + + /** + @overload + */ void DrawEllipse(const wxRect& rect); - //@} /** Draws an arc of an ellipse. The current pen is used for drawing the arc @@ -253,6 +356,12 @@ public: void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double start, double end); + /** + @overload + */ + void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, + double sa, double ea); + /** Draw an icon on the display (does nothing if the device context is PostScript). This can be the simplest way of drawing bitmaps on a @@ -260,21 +369,28 @@ public: */ void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); - //@{ + /** + @overload + */ + void DrawIcon(const wxIcon& icon, const wxPoint& pt); + /** Draw optional bitmap and the text into the given rectangle and aligns it as specified by alignment parameter; it also will emphasize the 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); + + /** + @overload + */ void DrawLabel(const wxString& text, const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1); - //@} /** Draws a line from the first point to the second. The current pen is @@ -284,14 +400,18 @@ public: */ void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); + /** + @overload + */ + void DrawLine(const wxPoint& pt1, const wxPoint& pt2); + /** Draws lines using an array of points of size @a n adding the optional offset coordinate. The current pen is used for drawing the lines. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0); @@ -300,10 +420,11 @@ public: coordinate. The programmer is responsible for deleting the list of points. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly + @beginWxPerlOnly + The wxPerl version of this method accepts + as its first parameter a reference to an array + of wxPoint objects. + @endWxPerlOnly */ void DrawLines(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0); @@ -314,6 +435,11 @@ public: */ void DrawPoint(wxCoord x, wxCoord y); + /** + @overload + */ + void DrawPoint(const wxPoint& pt); + /** Draws a filled polygon using an array of points of size @a n, adding the optional offset coordinate. The first and last points are @@ -324,6 +450,10 @@ public: The current pen is used for drawing the outline, and the current brush for filling the shape. Using a transparent brush suppresses filling. + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -341,10 +471,11 @@ public: The programmer is responsible for deleting the list of points. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly + @beginWxPerlOnly + The wxPerl version of this method accepts + as its first parameter a reference to an array + of wxPoint objects. + @endWxPerlOnly */ void DrawPolygon(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -372,10 +503,6 @@ public: call to DrawPolyPolygon() must be closed. Unlike polygons created by the DrawPolygon() member function, the polygons created by this method are not closed automatically. - - @beginWxPythonOnly - Not implemented yet. - @endWxPythonOnly */ void DrawPolyPolygon(int n, int count[], wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, @@ -389,7 +516,18 @@ public: void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); /** - Draws the text rotated by @a angle degrees. + @overload + */ + void DrawRectangle(const wxPoint& pt, const wxSize& sz); + + /** + @overload + */ + void DrawRectangle(const wxRect& rect); + + /** + Draws the text rotated by @a angle degrees + (positive angles are counterclockwise; the full angle is 360 degrees). @note Under Win9x only TrueType fonts can be drawn by this function. In particular, a font different from @c wxNORMAL_FONT should be used @@ -401,6 +539,12 @@ public: void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle); + /** + @overload + */ + void DrawRotatedText(const wxString& text, const wxPoint& point, + double angle); + /** Draws a rectangle with the given top left corner, and with the given size. The corners are quarter-circles using the given radius. The @@ -417,20 +561,48 @@ public: void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius); - //@{ + /** + @overload + */ + void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, + double radius); + + /** + @overload + */ + void DrawRoundedRectangle(const wxRect& rect, double radius); + /** Draws a spline between all given points using the current pen. - @beginWxPythonOnly - The wxPython version of this method accepts a Python list of wxPoint - objects. - @endWxPythonOnly + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ void DrawSpline(int n, wxPoint points[]); + + /** + @overload + + + @beginWxPerlOnly + The wxPerl version of this method accepts + as its first parameter a reference to an array + of wxPoint objects. + @endWxPerlOnly + */ void DrawSpline(const wxPointList* points); + + /** + @overload + + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly + */ void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, wxCoord y3); - //@} /** Draws a text string at the specified point, using the current text @@ -438,7 +610,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. @@ -446,112 +623,186 @@ public: void DrawText(const wxString& text, wxCoord x, wxCoord y); /** - Ends a document (only relevant when outputting to a printer). + @overload */ - void EndDoc(); + void DrawText(const wxString& text, const wxPoint& pt); /** - Ends a document page (only relevant when outputting to a printer). + Fill the area specified by rect with a radial gradient, starting from + @a initialColour at the centre of the circle and fading to + @a destColour on the circle outside. + + The circle is placed at the centre of @a rect. + + @note Currently this function is very slow, don't use it for real-time + drawing. */ - void EndPage(); + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour); /** - Flood fills the device context starting from the given point, using - the current brush colour, and using a style: + Fill the area specified by rect with a radial gradient, starting from + @a initialColour at the centre of the circle and fading to + @a destColour on the circle outside. - - wxFLOOD_SURFACE: The flooding occurs until a colour other than the - given colour is encountered. - - wxFLOOD_BORDER: The area to be flooded is bounded by the given - colour. + @a circleCenter are the relative coordinates of centre of the circle in + the specified @a rect. + + @note Currently this function is very slow, don't use it for real-time + drawing. + */ + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + const wxPoint& circleCenter); + + /** + Fill the area specified by @a rect with a linear gradient, starting + from @a initialColour and eventually fading to @e destColour. + + The @a nDirection specifies the direction of the colour change, default is + to use @a initialColour on the left part of the rectangle and + @a destColour on the right one. + */ + void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, + const wxColour& destColour, + wxDirection nDirection = wxRIGHT); + + /** + Flood fills the device context starting from the given point, using + the current brush colour, and using a style: + + - wxFLOOD_SURFACE: The flooding occurs until a colour other than the + given colour is encountered. + - wxFLOOD_BORDER: The area to be flooded is bounded by the given + colour. @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 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); /** - Gets the brush used for painting the background. - - @see wxDC::SetBackground() + @overload */ - const wxBrush& GetBackground() const; + bool FloodFill(const wxPoint& pt, const wxColour& col, + wxFloodFillStyle style = wxFLOOD_SURFACE); /** - Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - - @see SetBackgroundMode() + Displays a cross hair using the current pen. This is a vertical and + horizontal line the height and width of the window, centred on the + given point. */ - int GetBackgroundMode() const; + void CrossHair(wxCoord x, wxCoord y); /** - Gets the current brush. - - @see wxDC::SetBrush() + @overload */ - const wxBrush& GetBrush() const; + void CrossHair(const wxPoint& pt); + + //@} + /** - Gets the character height of the currently set font. + @name Clipping region functions */ - wxCoord GetCharHeight() const; + //@{ /** - Gets the average character width of the currently set font. + Destroys the current clipping region so that none of the DC is clipped. + + @see SetClippingRegion() */ - wxCoord GetCharWidth() const; + void DestroyClippingRegion(); /** Gets the rectangle surrounding the current clipping region. - - @beginWxPythonOnly - No arguments are required and the four values defining the rectangle - are returned as a tuple. - @endWxPythonOnly */ void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; /** - Returns the depth (number of bits/pixel) of this DC. + Sets the clipping region for this device context to the intersection of + the given region described by the parameters of this method and the + previously set clipping region. - @see wxDisplayDepth() + The clipping region is an area to which drawing is restricted. Possible + uses for the clipping region are for clipping text or for speeding up + window redraws when only a known area of the screen is damaged. + + Notice that you need to call DestroyClippingRegion() if you want to set + the clipping region exactly to the region specified. + + Also note that if the clipping region is empty, any previously set + clipping region is destroyed, i.e. it is equivalent to calling + DestroyClippingRegion(), and not to clipping out all drawing on the DC + as might be expected. + + @see DestroyClippingRegion(), wxRegion */ - int GetDepth() const; + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); /** - Gets the current font. Notice that even although each device context - object has some default font after creation, this method would return a - wxNullFont initially and only after calling SetFont() a valid font is - returned. + @overload */ - const wxFont& GetFont() const; + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); /** - Gets the current layout direction of the device context. On platforms - where RTL layout is supported, the return value will either be - @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is - not supported, the return value will be @c wxLayout_Default. - - @see SetLayoutDirection() + @overload */ - wxLayoutDirection GetLayoutDirection() const; + void SetClippingRegion(const wxRect& rect); /** - Gets the current logical function. + Sets the clipping region for this device context. - @see SetLogicalFunction() + Unlike SetClippingRegion(), this function works with physical + coordinates and not with the logical ones. + */ + void SetDeviceClippingRegion(const wxRegion& region); + + //@} + + + /** + @name Text/character extent functions */ - wxRasterOperationMode GetLogicalFunction() const; + //@{ /** - Gets the mapping mode for the device context. + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight() const; - @see SetMapMode() + /** + Gets the average character width of the currently set font. */ - wxMappingMode GetMapMode() const; + 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. @@ -566,6 +817,12 @@ public: @note This function works with both single-line and multi-line strings. + @beginWxPerlOnly + In wxPerl this method is implemented as + GetMultiLineTextExtent(string, font = undef) returning a + 3-element list (width, height, line_height) + @endWxPerlOnly + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ void GetMultiLineTextExtent(const wxString& string, wxCoord* w, @@ -581,6 +838,10 @@ public: @note This function works with both single-line and multi-line strings. + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly + @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ wxSize GetMultiLineTextExtent(const wxString& string) const; @@ -593,10 +854,10 @@ public: function that is faster or more accurate than the generic implementation then it should be used instead. - @beginWxPythonOnly - This method only takes the @a text parameter and returns a Python list - of integers. - @endWxPythonOnly + @beginWxPerlOnly + In wxPerl this method only takes the @a text parameter and + returns the widths as a list of integers. + @endWxPerlOnly @see GetMultiLineTextExtent(), GetTextExtent() */ @@ -604,64 +865,78 @@ public: wxArrayInt& widths) const; /** - Gets the current pen. + Gets the dimensions of the string using the currently selected font. + @a string is the text string to measure, @a descent is the dimension + from the baseline of the font to the bottom of the descender, and + @a externalLeading is any extra vertical space added to the font by the + font designer (usually is zero). - @see SetPen() + The text extent is returned in @a w and @a h pointers or as a wxSize + object depending on which version of this function is used. + + If the optional parameter @a font is specified and valid, then it is + used for the text extent calculation. Otherwise the currently selected + font is. + + @note This function only works with single-line strings. + + @beginWxPerlOnly + In wxPerl this method is implemented as GetTextExtent(string, + font = undef) returning a 4-element list (width, height, + descent, externalLeading) + @endWxPerlOnly + + @see wxFont, SetFont(), GetPartialTextExtents(), + GetMultiLineTextExtent() */ - const wxPen& GetPen() const; + void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, + wxCoord* descent = NULL, + wxCoord* externalLeading = NULL, + const wxFont* font = NULL) const; /** - Gets in @a colour the colour at the specified location. Not available - for wxPostScriptDC or wxMetafileDC. + @overload - @note Setting a pixel can be done using DrawPoint(). - @beginWxPythonOnly - The wxColour value is returned and is not required as a parameter. - @endWxPythonOnly + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ - bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; + wxSize GetTextExtent(const wxString& string) const; + + //@} + /** - Returns the resolution of the device in pixels per inch. + @name Text properties functions */ - wxSize GetPPI() const; - //@{ - /** - This gets the horizontal and vertical resolution in device units. 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 - code will scale the graphic to fit on the printer page: + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - @code - wxCoord w, h; - dc.GetSize(&w, &h); - double scaleX = (double)(maxX / w); - double scaleY = (double)(maxY / h); - dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); - @endcode + @see SetBackgroundMode() + */ + int GetBackgroundMode() const; - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the - following methods: - - GetSize() - Returns a wxSize. - - GetSizeWH() - Returns a 2-tuple (width, height). - @endWxPythonOnly + /** + Gets the current font. + + Notice that even although each device context object has some default font + after creation, this method would return a ::wxNullFont initially and only + after calling SetFont() a valid font is returned. */ - void GetSize(wxCoord* width, wxCoord* height) const; - wxSize GetSize() const; - //@} + const wxFont& GetFont() const; - //@{ /** - Returns the horizontal and vertical resolution in millimetres. + Gets the current layout direction of the device context. On platforms + where RTL layout is supported, the return value will either be + @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is + not supported, the return value will be @c wxLayout_Default. + + @see SetLayoutDirection() */ - void GetSizeMM(wxCoord* width, wxCoord* height) const; - wxSize GetSizeMM() const; - //@} + wxLayoutDirection GetLayoutDirection() const; /** Gets the current text background colour. @@ -670,145 +945,472 @@ public: */ const wxColour& GetTextBackground() const; + /** + Gets the current text foreground colour. + + @see SetTextForeground() + */ + const wxColour& GetTextForeground() const; + + /** + @a mode may be one of @c wxSOLID and @c wxTRANSPARENT. + + This setting determines whether text will be drawn with a background + colour or not. + */ + void SetBackgroundMode(int mode); + + /** + Sets the current font for the DC. + + If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk), + the current font is selected out of the device context (leaving wxDC without + any valid font), allowing the current font to be destroyed safely. + + @see wxFont + */ + void SetFont(const wxFont& font); + + /** + Sets the current text background colour for the DC. + */ + void SetTextBackground(const wxColour& colour); + + /** + Sets the current text foreground colour for the DC. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. + */ + void SetTextForeground(const wxColour& colour); + + /** + Sets the current layout direction for the device context. + + @param dir + May be either @c wxLayout_Default, @c wxLayout_LeftToRight or + @c wxLayout_RightToLeft. + + @see GetLayoutDirection() + */ + void SetLayoutDirection(wxLayoutDirection dir); + + //@} + + + /** + @name Bounding box functions + */ //@{ + /** - Gets the dimensions of the string using the currently selected font. - @a string is the text string to measure, @a descent is the dimension - from the baseline of the font to the bottom of the descender, and - @a externalLeading is any extra vertical space added to the font by the - font designer (usually is zero). + Adds the specified point to the bounding box which can be retrieved + with MinX(), MaxX() and MinY(), MaxY() functions. - The text extent is returned in @a w and @a h pointers or as a wxSize - object depending on which version of this function is used. + @see ResetBoundingBox() + */ + void CalcBoundingBox(wxCoord x, wxCoord y); - If the optional parameter @a font is specified and valid, then it is - used for the text extent calculation. Otherwise the currently selected - font is. + /** + Gets the maximum horizontal extent used in drawing commands so far. + */ + wxCoord MaxX() const; - @note This function only works with single-line strings. + /** + Gets the maximum vertical extent used in drawing commands so far. + */ + wxCoord MaxY() const; - @beginWxPythonOnly - The following methods are implemented in wxPython: - - GetTextExtent(string) - Returns a 2-tuple, (width, height). - - GetFullTextExtent(string, font=NULL) - - Returns a 4-tuple, (width, height, descent, externalLeading). - @endWxPythonOnly + /** + Gets the minimum horizontal extent used in drawing commands so far. + */ + wxCoord MinX() const; - @see wxFont, SetFont(), GetPartialTextExtents(), - GetMultiLineTextExtent() + /** + Gets the minimum vertical extent used in drawing commands so far. */ - void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, - wxCoord* descent = NULL, - wxCoord* externalLeading = NULL, - const wxFont* font = NULL) const; - wxSize GetTextExtent(const wxString& string) const; + wxCoord MinY() const; + + /** + Resets the bounding box: after a call to this function, the bounding + box doesn't contain anything. + + @see CalcBoundingBox() + */ + void ResetBoundingBox(); + //@} + /** - Gets the current text foreground colour. + @name Page and document start/end functions + */ + //@{ - @see SetTextForeground() + /** + Starts a document (only relevant when outputting to a printer). + @a message is a message to show while printing. */ - const wxColour& GetTextForeground() const; + bool StartDoc(const wxString& message); /** - Gets the current user scale factor. + Starts a document page (only relevant when outputting to a printer). + */ + void StartPage(); - @see SetUserScale() + /** + Ends a document (only relevant when outputting to a printer). */ - void GetUserScale(double* x, double* y) const; + void EndDoc(); + + /** + Ends a document page (only relevant when outputting to a printer). + */ + void EndPage(); + + //@} + + /** + @name Bit-Block Transfer operations (blit) + */ //@{ + /** - Fill the area specified by rect with a radial gradient, starting from - @a initialColour at the centre of the circle and fading to - @a destColour on the circle outside. + Copy from a source DC to this DC. - @a circleCenter are the relative coordinates of centre of the circle in - the specified @e rect. If not specified, the circle is placed at the - centre of rect. + With this method you can specify the destination coordinates and the + size of area to copy which will be the same for both the source and + target DCs. If you need to apply scaling while copying, use + StretchBlit(). - @note Currently this function is very slow, don't use it for real-time - drawing. + Notice that source DC coordinates @a xsrc and @a ysrc are interpreted + using the current source DC coordinate system, i.e. the scale, origin + position and axis directions are taken into account when transforming + them to physical (pixel) coordinates. + + @param xdest + Destination device context x position. + @param ydest + Destination device context y position. + @param width + Width of source area to be copied. + @param height + Height of source area to be copied. + @param source + Source device context. + @param xsrc + Source device context x position. + @param ysrc + Source device context y position. + @param logicalFunc + Logical function to use, see SetLogicalFunction(). + @param useMask + If @true, Blit does a transparent blit using the mask that is + associated with the bitmap selected into the source device context. + The Windows implementation does the following if MaskBlt cannot be + used: +
    +
  1. Creates a temporary bitmap and copies the destination area into + it.
  2. +
  3. Copies the source area into the temporary bitmap using the + specified logical function.
  4. +
  5. Sets the masked area in the temporary bitmap to BLACK by ANDing + the mask bitmap with the temp bitmap with the foreground colour + set to WHITE and the bg colour set to BLACK.
  6. +
  7. Sets the unmasked area in the destination area to BLACK by + ANDing the mask bitmap with the destination area with the + foreground colour set to BLACK and the background colour set to + WHITE.
  8. +
  9. ORs the temporary bitmap with the destination area.
  10. +
  11. Deletes the temporary bitmap.
  12. +
+ 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_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. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are + @c -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are + @c -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + + @remarks There is partial support for Blit() in wxPostScriptDC, under X. + + @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask */ - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour); - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour, - const wxPoint& circleCenter); + bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, + wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, + wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, + wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); + + /** + Copy from a source DC to this DC possibly changing the scale. + + Unlike Blit(), this method allows to specify different source and + destination region sizes, meaning that it can stretch or shrink it + while copying. The same can be achieved by changing the scale of the + source or target DC but calling this method is simpler and can also be + more efficient if the platform provides a native implementation of it. + + The meaning of its other parameters is the same as with Blit(), in + particular all source coordinates are interpreted using the source DC + coordinate system, i.e. are affected by its scale, origin translation + and axis direction. + + @param xdest + Destination device context x position. + @param ydest + Destination device context y position. + @param dstWidth + Width of destination area. + @param dstHeight + Height of destination area. + @param source + Source device context. + @param xsrc + Source device context x position. + @param ysrc + Source device context y position. + @param srcWidth + Width of source area to be copied. + @param srcHeight + Height of source area to be copied. + @param logicalFunc + Logical function to use, see SetLogicalFunction(). + @param useMask + If @true, Blit does a transparent blit using the mask that is + associated with the bitmap selected into the source device context. + The Windows implementation does the following if MaskBlt cannot be + used: +
    +
  1. Creates a temporary bitmap and copies the destination area into + it.
  2. +
  3. Copies the source area into the temporary bitmap using the + specified logical function.
  4. +
  5. Sets the masked area in the temporary bitmap to BLACK by ANDing + the mask bitmap with the temp bitmap with the foreground colour + set to WHITE and the bg colour set to BLACK.
  6. +
  7. Sets the unmasked area in the destination area to BLACK by + ANDing the mask bitmap with the destination area with the + foreground colour set to BLACK and the background colour set to + WHITE.
  8. +
  9. ORs the temporary bitmap with the destination area.
  10. +
  11. Deletes the temporary bitmap.
  12. +
+ 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_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. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are + wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask + source position. Currently only implemented on Windows. + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are + wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask + source position. Currently only implemented on Windows. + + There is partial support for Blit() in wxPostScriptDC, under X. + + See wxMemoryDC for typical usage. + + @since 2.9.0 + + @see Blit(), wxMemoryDC, wxBitmap, wxMask + */ + bool StretchBlit(wxCoord xdest, wxCoord ydest, + wxCoord dstWidth, wxCoord dstHeight, + wxDC* source, wxCoord xsrc, wxCoord ysrc, + wxCoord srcWidth, wxCoord srcHeight, + wxRasterOperationMode logicalFunc = wxCOPY, + bool useMask = false, + wxCoord xsrcMask = wxDefaultCoord, + wxCoord ysrcMask = wxDefaultCoord); //@} + + /** + @name Background/foreground brush and pen + */ + //@{ + + /** + Gets the brush used for painting the background. + + @see wxDC::SetBackground() + */ + const wxBrush& GetBackground() const; + + /** + Gets the current brush. + + @see wxDC::SetBrush() + */ + const wxBrush& GetBrush() const; + + /** + Gets the current pen. + + @see SetPen() + */ + const wxPen& GetPen() const; + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + Sets the current brush for the DC. + + If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk), + the current brush is selected out of the device context (leaving wxDC without + any valid brush), allowing the current brush to be destroyed safely. + + @see wxBrush, wxMemoryDC (for the interpretation of colours when + drawing into a monochrome bitmap) + */ + void SetBrush(const wxBrush& brush); + + /** + Sets the current pen for the DC. + + If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk), + the current pen is selected out of the device context (leaving wxDC without any + valid pen), allowing the current pen to be destroyed safely. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. + */ + void SetPen(const wxPen& pen); + + //@} + + + /** + Copy attributes from another DC. + + The copied attributes currently are: + - Font + - Text foreground and background colours + - Background brush + - Layout direction + + @param dc + A valid (i.e. its IsOk() must return @true) source device context. + */ + void CopyAttributes(const wxDC& dc); + + /** + Returns the depth (number of bits/pixel) of this DC. + + @see wxDisplayDepth() + */ + int GetDepth() const; + /** - Fill the area specified by @a rect with a linear gradient, starting - from @a initialColour and eventually fading to @e destColour. The - @a nDirection specifies the direction of the colour change, default is - to use @a initialColour on the left part of the rectangle and - @a destColour on the right one. + Returns the current device origin. + + @see SetDeviceOrigin() */ - void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, - const wxColour& destColour, - wxDirection nDirection = wxRIGHT); + wxPoint GetDeviceOrigin() const; /** - Returns @true if the DC is ok to use. + Gets the current logical function. + + @see SetLogicalFunction() */ - bool IsOk() const; + wxRasterOperationMode GetLogicalFunction() const; /** - Converts logical X coordinate to device coordinate, using the current - mapping mode, user scale factor, device origin and axis orientation. + Gets the current mapping mode for the device context. + + @see SetMapMode() */ - wxCoord LogicalToDeviceX(wxCoord x) const; + wxMappingMode GetMapMode() const; /** - Converts logical X coordinate to relative device coordinate, using the - current mapping mode and user scale factor but ignoring the - axis orientation. Use this for converting a width, for example. + Gets in @a colour the colour at the specified location. Not available + for wxPostScriptDC or wxMetafileDC. + + @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. */ - wxCoord LogicalToDeviceXRel(wxCoord x) const; + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; /** - Converts logical Y coordinate to device coordinate, using the current - mapping mode, user scale factor, device origin and axis orientation. + Returns the resolution of the device in pixels per inch. */ - wxCoord LogicalToDeviceY(wxCoord y) const; + wxSize GetPPI() const; /** - Converts logical Y coordinate to relative device coordinate, using the - current mapping mode and user scale factor but ignoring the - axis orientation. Use this for converting a height, for example. + Gets the horizontal and vertical extent of this device context in @e device units. + 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 + code will scale the graphic to fit on the printer page: + + @code + wxCoord w, h; + dc.GetSize(&w, &h); + double scaleX = (double)(maxX / w); + double scaleY = (double)(maxY / h); + dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); + @endcode + + @beginWxPerlOnly + In wxPerl there are two methods instead of a single overloaded + method: + - GetSize(): returns a Wx::Size object. + - GetSizeWH(): returns a 2-element list (width, height). + @endWxPerlOnly */ - wxCoord LogicalToDeviceYRel(wxCoord y) const; + void GetSize(wxCoord* width, wxCoord* height) const; /** - Gets the maximum horizontal extent used in drawing commands so far. + @overload */ - wxCoord MaxX() const; + wxSize GetSize() const; /** - Gets the maximum vertical extent used in drawing commands so far. + Returns the horizontal and vertical resolution in millimetres. */ - wxCoord MaxY() const; + void GetSizeMM(wxCoord* width, wxCoord* height) const; /** - Gets the minimum horizontal extent used in drawing commands so far. + @overload */ - wxCoord MinX() const; + wxSize GetSizeMM() const; /** - Gets the minimum vertical extent used in drawing commands so far. + Gets the current user scale factor. + + @beginWxPerlOnly + In wxPerl this method takes no arguments and return a two + element array (x, y). + @endWxPerlOnly + + @see SetUserScale() */ - wxCoord MinY() const; + void GetUserScale(double* x, double* y) const; /** - Resets the bounding box: after a call to this function, the bounding - box doesn't contain anything. - - @see CalcBoundingBox() + Returns @true if the DC is ok to use. */ - void ResetBoundingBox(); + bool IsOk() const; /** Sets the x and y axis orientation (i.e., the direction from lowest to @@ -824,56 +1426,6 @@ public: */ void SetAxisOrientation(bool xLeftRight, bool yBottomUp); - /** - Sets the current background brush for the DC. - */ - void SetBackground(const wxBrush& brush); - - /** - @a mode may be one of wxSOLID and wxTRANSPARENT. This setting - determines whether text will be drawn with a background colour or not. - */ - void SetBackgroundMode(int mode); - - /** - Sets the current brush for the DC. - - If the argument is wxNullBrush, the current brush is selected out of - the device context (leaving wxDC without any valid brush), allowing the - current brush to be destroyed safely. - - @see wxBrush, wxMemoryDC (for the interpretation of colours when - drawing into a monochrome bitmap) - */ - void SetBrush(const wxBrush& brush); - - //@{ - /** - Sets the clipping region for this device context to the intersection of - the given region described by the parameters of this method and the - previously set clipping region. You should call DestroyClippingRegion() - if you want to set the clipping region exactly to the region specified. - - The clipping region is an area to which drawing is restricted. Possible - uses for the clipping region are for clipping text or for speeding up - window redraws when only a known area of the screen is damaged. - - @see DestroyClippingRegion(), wxRegion - */ - void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - void SetClippingRegion(const wxPoint& pt, const wxSize& sz); - void SetClippingRegion(const wxRect& rect); - //@} - - /** - 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 @@ -882,63 +1434,27 @@ public: void SetDeviceOrigin(wxCoord x, wxCoord y); /** - Sets the current font for the DC. It must be a valid font, in - particular you should not pass wxNullFont to this method. - - @see wxFont - */ - void SetFont(const wxFont& font); - - /** - Sets the current layout direction for the device context. @a dir may be - either @c wxLayout_Default, @c wxLayout_LeftToRight or - @c wxLayout_RightToLeft. - - @see GetLayoutDirection() - */ - void SetLayoutDirection(wxLayoutDirection dir); - - /** - Sets the current logical function for the device context. This - determines how a source pixel (from a pen or brush colour, or source - device context if using Blit()) combines with a destination pixel in + Sets the current logical function for the device context. + It determines how a @e source pixel (from a pen or brush colour, or source + device context if using Blit()) combines with a @e destination pixel in the current device context. Text drawing is not affected by this function. - The possible values and their meaning in terms of source and - destination pixel values are as follows: - - @verbatim - wxAND src AND dst - wxAND_INVERT (NOT src) AND dst - wxAND_REVERSE src AND (NOT dst) - wxCLEAR 0 - wxCOPY src - wxEQUIV (NOT src) XOR dst - wxINVERT NOT dst - wxNAND (NOT src) OR (NOT dst) - wxNOR (NOT src) AND (NOT dst) - wxNO_OP dst - wxOR src OR dst - wxOR_INVERT (NOT src) OR dst - wxOR_REVERSE src OR (NOT dst) - wxSET 1 - wxSRC_INVERT NOT src - wxXOR src XOR dst - @endverbatim - - The default is wxCOPY, which simply draws with the current colour. The - others combine the current colour and the background using a logical - operation. wxINVERT is commonly used for drawing rubber bands or moving + See ::wxRasterOperationMode enumeration values for more info. + + The default is @c wxCOPY, which simply draws with the current colour. + The others combine the current colour and the background using a logical + operation. @c wxINVERT is commonly used for drawing rubber bands or moving outlines, since drawing twice reverts to the original colour. */ void SetLogicalFunction(wxRasterOperationMode function); /** The mapping mode of the device context defines the unit of measurement - used to convert logical units to 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 + 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 SetUserScale()) scales the text appropriately. In Windows, scalable TrueType fonts are always used; in X, results depend on availability of fonts, but usually a reasonable match is found. @@ -947,21 +1463,13 @@ public: Drawing to a Windows printer device context uses the current mapping mode, but mapping mode is currently ignored for PostScript output. - - The mapping mode can be one of the following: - - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an - inch. - - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch. - - wxMM_METRIC: Each logical unit is 1 mm. - - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm. - - wxMM_TEXT: Each logical unit is 1 device pixel. */ void SetMapMode(wxMappingMode mode); /** If this is a window DC or memory DC, assigns the given palette to the window or bitmap associated with the DC. If the argument is - wxNullPalette, the current palette is selected out of the device + ::wxNullPalette, the current palette is selected out of the device context, and the original palette restored. @see wxPalette @@ -969,125 +1477,70 @@ public: void SetPalette(const wxPalette& palette); /** - Sets the current pen for the DC. If the argument is wxNullPen, the - current pen is selected out of the device context (leaving wxDC without - any valid pen), allowing the current brush to be destroyed safely. - - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. + Sets the user scaling factor, useful for applications which require + 'zooming'. */ - void SetPen(const wxPen& pen); + void SetUserScale(double xScale, double yScale); - /** - Sets the current text background colour for the DC. - */ - void SetTextBackground(const wxColour& colour); /** - Sets the current text foreground colour for the DC. + @name Transformation matrix - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. + See the notes about the availability of these functions in the class + documentation. */ - void SetTextForeground(const wxColour& colour); + //@{ /** - Sets the user scaling factor, useful for applications which require - 'zooming'. - */ - void SetUserScale(double xScale, double yScale); + Check if the use of transformation matrix is supported by the current + system. - /** - Starts a document (only relevant when outputting to a printer). - @a message is a message to show while printing. + 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 StartDoc(const wxString& message); + bool CanUseTransformMatrix() const; /** - Starts a document page (only relevant when outputting to a printer). + 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 */ - void StartPage(); + bool SetTransformMatrix(const wxAffineMatrix2D& matrix); /** - Copy from a source DC to this DC, specifying the destination - coordinates, destination size, source DC, source coordinates, size of - source area to copy, logical function, whether to use a bitmap mask, - and mask source position. + Return the transformation matrix used by this device context. - @param xdest - Destination device context x position. - @param ydest - Destination device context y position. - @param dstWidth - Width of destination area. - @param dstHeight - Height of destination area. - @param source - Source device context. - @param xsrc - Source device context x position. - @param ysrc - Source device context y position. - @param srcWidth - Width of source area to be copied. - @param srcHeight - Height of source area to be copied. - @param logicalFunc - Logical function to use, see SetLogicalFunction(). - @param useMask - If @true, Blit does a transparent blit using the mask that is - associated with the bitmap selected into the source device context. - The Windows implementation does the following if MaskBlt cannot be - used: -
    -
  1. Creates a temporary bitmap and copies the destination area into - it.
  2. -
  3. Copies the source area into the temporary bitmap using the - specified logical function.
  4. -
  5. Sets the masked area in the temporary bitmap to BLACK by ANDing - the mask bitmap with the temp bitmap with the foreground colour - set to WHITE and the bg colour set to BLACK.
  6. -
  7. Sets the unmasked area in the destination area to BLACK by - ANDing the mask bitmap with the destination area with the - foreground colour set to BLACK and the background colour set to - WHITE.
  8. -
  9. ORs the temporary bitmap with the destination area.
  10. -
  11. Deletes the temporary bitmap.
  12. -
- 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 - 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. - @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are - wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask - source position. Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are - wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask - source position. Currently only implemented on Windows. + By default the transformation matrix is the identity matrix. - There is partial support for Blit() in wxPostScriptDC, under X. + @since 2.9.2 + */ + wxAffineMatrix2D GetTransformMatrix() const; - StretchBlit() is only implemented under wxMAC and wxMSW. + /** + Revert the transformation matrix to identity matrix. - See wxMemoryDC for typical usage. + @since 2.9.2 + */ + void ResetTransformMatrix(); - @since 2.9.0 + //@} - @see Blit(), wxMemoryDC, wxBitmap, wxMask - */ - bool StretchBlit(wxCoord xdest, wxCoord ydest, - wxCoord dstWidth, wxCoord dstHeight, - wxDC* source, wxCoord xsrc, wxCoord ysrc, - wxCoord srcWidth, wxCoord srcHeight, - wxRasterOperationMode logicalFunc = wxCOPY, - bool useMask = false, - wxCoord xsrcMask = wxDefaultCoord, - wxCoord ysrcMask = wxDefaultCoord); + + 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; + }; @@ -1095,10 +1548,12 @@ public: /** @class wxDCClipper - wxDCClipper is a small helper class for setting a clipping region on a wxDC - and unsetting it automatically. An object of wxDCClipper class is typically - created on the stack so that it is automatically destroyed when the object - goes out of scope. A typical usage example: + wxDCClipper is a helper class for setting a clipping region on a wxDC + during its lifetime. + + An object of wxDCClipper class is typically created on the stack so that it + is automatically destroyed when the object goes out of scope. A typical + usage example: @code void MyFunction(wxDC& dc) @@ -1115,6 +1570,12 @@ public: } @endcode + @note Unlike other similar classes such as wxDCFontChanger, wxDCClipper + currently doesn't restore the previously active clipping region when it + is destroyed but simply resets clipping on the associated wxDC. This + may be changed in the future wxWidgets versions but has to be taken + into account explicitly in the current one. + @library{wxcore} @category{gdi} @@ -1130,7 +1591,7 @@ public: 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); //@} @@ -1223,6 +1684,16 @@ public: class wxDCTextColourChanger { public: + /** + Trivial constructor not changing anything. + + This constructor is useful if you don't know beforehand if the colour + needs to be changed or not. It simply creates the object which won't do + anything in its destructor unless Set() is called -- in which case it + would reset the previous colour. + */ + wxDCTextColourChanger(wxDC& dc); + /** Sets @a col on the given @a dc, storing the old one. @@ -1233,6 +1704,17 @@ public: */ wxDCTextColourChanger(wxDC& dc, const wxColour& col); + /** + Set the colour to use. + + This method is meant to be called once only and only on the objects + created with the constructor overload not taking wxColour argument and + has the same effect as the other constructor, i.e. sets the colour to + the given @a col and ensures that the old value is restored when this + object is destroyed. + */ + void Set(const wxColour& col); + /** Restores the colour originally selected in the DC passed to the ctor. */ @@ -1258,6 +1740,18 @@ public: class wxDCFontChanger { public: + /** + Trivial constructor not changing anything. + + This constructor is useful if you don't know beforehand if the font + needs to be changed or not. It simply creates the object which won't do + anything in its destructor unless Set() is called -- in which case it + would reset the previous font. + + @since 2.9.1 + */ + wxDCFontChanger(wxDC& dc); + /** Sets @a font on the given @a dc, storing the old one. @@ -1269,7 +1763,18 @@ public: wxDCFontChanger(wxDC& dc, const wxFont& font); /** - Restores the colour originally selected in the DC passed to the ctor. + Set the font to use. + + This method is meant to be called once only and only on the objects + created with the constructor overload not taking wxColour argument and + has the same effect as the other constructor, i.e. sets the font to + the given @a font and ensures that the old value is restored when this + object is destroyed. + */ + void Set(const wxFont& font); + + /** + Restores the font originally selected in the DC passed to the ctor. */ ~wxDCFontChanger(); };