X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4ccf05663316e28d964c7d76dc5defe774b59427..ca282726be518ce2f214b890dbaafce736f14e36:/interface/wx/dc.h?ds=sidebyside diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 55d29cb45c..d496f73703 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,155 +134,146 @@ 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} - @see @ref overview_dc, wxGraphicsContext + @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger, + wxDCPenChanger, wxDCBrushChanger, wxDCClipper @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. -
  2. Copies the source area into the temporary bitmap using the - specified logical function.
    3. -
  3. 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.
    4. -
  4. 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.
    5. -
  5. ORs the temporary bitmap with the destination area.
    6. -
  6. Deletes the temporary bitmap.
    7. -
- 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 - -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 - -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, - int 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 @@ -202,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 @@ -229,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 @@ -252,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 @@ -259,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. */ - virtual void DrawLabel(const wxString& text, const wxBitmap& image, - const wxRect& rect, - int alignment = wxALIGN_LEFT | wxALIGN_TOP, - int indexAccel = -1, wxRect* rectBounding = NULL); + 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 @@ -283,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); @@ -299,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); @@ -313,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 @@ -323,9 +450,14 @@ 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, int fill_style = wxODDEVEN_RULE); + wxCoord yoffset = 0, + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** This method draws a filled polygon using a list of wxPoints, adding the optional offset coordinate. The first and last points are automatically @@ -339,14 +471,15 @@ 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, - int fill_style = wxODDEVEN_RULE); + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** Draws two or more filled polygons using an array of @a points, adding @@ -370,14 +503,10 @@ 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, - int fill_style = wxODDEVEN_RULE); + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** Draws a rectangle with the given top left corner, and with the given @@ -387,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 @@ -399,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 @@ -415,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 @@ -436,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. @@ -444,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. - @return @false if the operation failed. + @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, - int style = wxFLOOD_SURFACE); + 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 */ - int 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. */ - int 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. @@ -564,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, @@ -579,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; @@ -591,84 +854,16 @@ 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() */ bool GetPartialTextExtents(const wxString& text, wxArrayInt& widths) const; - /** - Gets the current pen. - - @see SetPen() - */ - const wxPen& GetPen() const; - - /** - 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(). - - @beginWxPythonOnly - The wxColour value is returned and is not required as a parameter. - @endWxPythonOnly - */ - bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; - - /** - Returns the resolution of the device in pixels per inch. - */ - 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: - - @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 - - @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 - */ - void GetSize(wxCoord* width, wxCoord* height) const; - const wxSize GetSize() const; - //@} - - //@{ - /** - Returns the horizontal and vertical resolution in millimetres. - */ - void GetSizeMM(wxCoord* width, wxCoord* height) const; - const wxSize GetSizeMM() const; - //@} - - /** - Gets the current text background colour. - - @see SetTextBackground() - */ - const wxColour& GetTextBackground() const; - - //@{ /** Gets the dimensions of the string using the currently selected font. @a string is the text string to measure, @a descent is the dimension @@ -685,12 +880,11 @@ public: @note This function only works with single-line strings. - @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 + @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() @@ -699,318 +893,276 @@ public: wxCoord* descent = NULL, wxCoord* externalLeading = NULL, const wxFont* font = NULL) const; - const wxSize GetTextExtent(const wxString& string) const; - //@} /** - Gets the current text foreground colour. - - @see SetTextForeground() - */ - const wxColour& GetTextForeground() const; + @overload - /** - Gets the current user scale factor. - @see SetUserScale() + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ - void GetUserScale(double* x, double* y) const; - - //@{ - /** - 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. - - @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. + wxSize GetTextExtent(const wxString& string) const; - @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); - 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. + @name Text properties functions */ - void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, - const wxColour& destColour, - wxDirection nDirection = wxRIGHT); + //@{ /** - Returns @true if the DC is ok to use. + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + + @see SetBackgroundMode() */ - bool IsOk() const; + int GetBackgroundMode() const; /** - Converts logical X coordinate to device coordinate, using the current - mapping mode, user scale factor, device origin and axis orientation. + 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. */ - wxCoord LogicalToDeviceX(wxCoord x) const; + const wxFont& GetFont() 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 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() */ - wxCoord LogicalToDeviceXRel(wxCoord x) const; + wxLayoutDirection GetLayoutDirection() const; /** - Converts logical Y coordinate to device coordinate, using the current - mapping mode, user scale factor, device origin and axis orientation. + Gets the current text background colour. + + @see SetTextBackground() */ - wxCoord LogicalToDeviceY(wxCoord y) const; + const wxColour& GetTextBackground() 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 current text foreground colour. + + @see SetTextForeground() */ - wxCoord LogicalToDeviceYRel(wxCoord y) const; + const wxColour& GetTextForeground() const; /** - Gets the maximum horizontal extent used in drawing commands so far. + @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. */ - wxCoord MaxX() const; + void SetBackgroundMode(int mode); /** - Gets the maximum vertical extent used in drawing commands so far. + 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 */ - wxCoord MaxY() const; + void SetFont(const wxFont& font); /** - Gets the minimum horizontal extent used in drawing commands so far. + Sets the current text background colour for the DC. */ - wxCoord MinX() const; + void SetTextBackground(const wxColour& colour); /** - Gets the minimum vertical extent used in drawing commands so far. + Sets the current text foreground colour for the DC. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. */ - wxCoord MinY() const; + void SetTextForeground(const wxColour& colour); /** - Resets the bounding box: after a call to this function, the bounding - box doesn't contain anything. + 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 CalcBoundingBox() + @see GetLayoutDirection() */ - void ResetBoundingBox(); + void SetLayoutDirection(wxLayoutDirection dir); - /** - Sets the x and y axis orientation (i.e., the direction from lowest to - highest values on the axis). The default orientation is x axis from - left to right and y axis from top down. + //@} - @param xLeftRight - True to set the x axis orientation to the natural left to right - orientation, @false to invert it. - @param yBottomUp - True to set the y axis orientation to the natural bottom up - orientation, @false to invert it. - */ - void SetAxisOrientation(bool xLeftRight, bool yBottomUp); /** - Sets the current background brush for the DC. + @name Bounding box functions */ - 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. + Adds the specified point to the bounding box which can be retrieved + with MinX(), MaxX() and MinY(), MaxY() functions. + + @see ResetBoundingBox() */ - void SetBackgroundMode(int mode); + void CalcBoundingBox(wxCoord x, wxCoord y); /** - 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) + Gets the maximum horizontal extent used in drawing commands so far. */ - void SetBrush(const wxBrush& brush); + wxCoord MaxX() const; - //@{ /** - 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 + Gets the maximum vertical extent used in drawing commands so far. */ - void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - void SetClippingRegion(const wxPoint& pt, const wxSize& sz); - void SetClippingRegion(const wxRect& rect); - //@} + wxCoord MaxY() const; /** - 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); + Gets the minimum horizontal extent used in drawing commands so far. + */ + wxCoord MinX() const; /** - Sets the device origin (i.e., the origin in pixels after scaling has - been applied). This function may be useful in Windows printing - operations for placing a graphic on a page. + Gets the minimum vertical extent used in drawing commands so far. */ - void SetDeviceOrigin(wxCoord x, wxCoord y); + wxCoord MinY() const; /** - Sets the current font for the DC. It must be a valid font, in - particular you should not pass wxNullFont to this method. + Resets the bounding box: after a call to this function, the bounding + box doesn't contain anything. - @see wxFont + @see CalcBoundingBox() */ - void SetFont(const wxFont& font); + void ResetBoundingBox(); - /** - 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 - 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 - outlines, since drawing twice reverts to the original colour. + @name Page and document start/end functions */ - void SetLogicalFunction(int 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 - 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. - - The coordinate origin is always at the top left of the screen/printer. - - 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. + Starts a document (only relevant when outputting to a printer). + @a message is a message to show while printing. */ - void SetMapMode(int mode); + bool StartDoc(const wxString& message); /** - 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 - context, and the original palette restored. - - @see wxPalette + Starts a document page (only relevant when outputting to a printer). */ - void SetPalette(const wxPalette& palette); + void StartPage(); /** - 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. + Ends a document (only relevant when outputting to a printer). */ - void SetPen(const wxPen& pen); + void EndDoc(); /** - Sets the current text background colour for the DC. + Ends a document page (only relevant when outputting to a printer). */ - void SetTextBackground(const wxColour& colour); + void EndPage(); - /** - 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 user scaling factor, useful for applications which require - 'zooming'. + @name Bit-Block Transfer operations (blit) */ - void SetUserScale(double xScale, double yScale); + //@{ /** - Starts a document (only relevant when outputting to a printer). - @a message is a message to show while printing. - */ - bool StartDoc(const wxString& message); + Copy from a source DC to this DC. - /** - Starts a document page (only relevant when outputting to a printer). + 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(). + + 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. +
  2. Copies the source area into the temporary bitmap using the + specified logical function.
    3. +
  3. 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.
    4. +
  4. 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.
    5. +
  5. ORs the temporary bitmap with the destination area.
    6. +
  6. Deletes the temporary bitmap.
    7. +
+ 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 StartPage(); + 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, 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. + 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. @@ -1055,7 +1207,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. @@ -1070,8 +1222,6 @@ public: There is partial support for Blit() in wxPostScriptDC, under X. - StretchBlit() is only implemented under wxMAC and wxMSW. - See wxMemoryDC for typical usage. @since 2.9.0 @@ -1082,54 +1232,589 @@ public: wxCoord dstWidth, wxCoord dstHeight, wxDC* source, wxCoord xsrc, wxCoord ysrc, wxCoord srcWidth, wxCoord srcHeight, - int logicalFunc = wxCOPY, + 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. -/** - @class wxDCClipper + @see wxDC::SetBackground() + */ + const wxBrush& GetBackground() const; - 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: + /** + Gets the current brush. - @code - void MyFunction(wxDC& dc) - { - wxDCClipper clip(dc, rect); - // ... drawing functions here are affected by clipping rect ... - } + @see wxDC::SetBrush() + */ + const wxBrush& GetBrush() const; - void OtherFunction() - { - wxDC dc; - MyFunction(dc); - // ... drawing functions here are not affected by clipping rect ... - } - @endcode + /** + Gets the current pen. - @library{wxcore} - @category{gdi} + @see SetPen() + */ + const wxPen& GetPen() const; - @see wxDC::SetClippingRegion() -*/ -class wxDCClipper -{ -public: - //@{ /** - Sets the clipping region to the specified region/coordinates. + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); - The clipping region is automatically unset when this object is destroyed. + /** + 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) */ - wxDCClipper(wxDC& dc, const wxRegion& r); - wxDCClipper(wxDC& dc, const wxRect& rect); - wxDCClipper(wxDC& dc, int x, int y, int w, int h); + 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; + + /** + Returns the current device origin. + + @see SetDeviceOrigin() + */ + wxPoint GetDeviceOrigin() const; + + /** + Gets the current logical function. + + @see SetLogicalFunction() + */ + wxRasterOperationMode GetLogicalFunction() const; + + /** + Gets the current mapping mode for the device context. + + @see SetMapMode() + */ + wxMappingMode GetMapMode() const; + + /** + 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. + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; + + /** + Returns the resolution of the device in pixels per inch. + */ + wxSize GetPPI() const; + + /** + 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 + */ + void GetSize(wxCoord* width, wxCoord* height) const; + + /** + @overload + */ + wxSize GetSize() const; + + /** + Returns the horizontal and vertical resolution in millimetres. + */ + void GetSizeMM(wxCoord* width, wxCoord* height) const; + + /** + @overload + */ + wxSize GetSizeMM() const; + + /** + 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() + */ + void GetUserScale(double* x, double* y) const; + + /** + Returns @true if the DC is ok to use. + */ + bool IsOk() const; + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is x axis from + left to right and y axis from top down. + + @param xLeftRight + True to set the x axis orientation to the natural left to right + orientation, @false to invert it. + @param yBottomUp + True to set the y axis orientation to the natural bottom up + orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the device origin (i.e., the origin in pixels after scaling has + been applied). This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + 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. + + 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 @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. + + The coordinate origin is always at the top left of the screen/printer. + + Drawing to a Windows printer device context uses the current mapping + mode, but mapping mode is currently ignored for PostScript output. + */ + 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 + context, and the original palette restored. + + @see wxPalette + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the user scaling factor, useful for applications which require + '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(); + + //@} + + + /** + @name query capabilities + */ + //@{ + + /** + Does the DC support drawing bitmaps? + */ + bool CanDrawBitmap() const; + + /** + Does the DC supoprt calculating the size required to draw text? + */ + bool CanGetTextExtent() const; + + //@} + + /** + Returns a value that can be used as a handle to the native drawing + context, if this wxDC has something that could be thought of in that + way. (Not all of them do.) + + For example, on Windows the return value is an HDC, on OSX it is a + CGContextRef and on wxGTK it will be a GdkDrawable. If the DC is a + wxGCDC then the return value will be the value returned from + wxGraphicsContext::GetNativeContext. A value of NULL is returned if + the DC does not have anything that fits the handle concept. + + @since 2.9.5 + */ + void* GetHandle() const; + + + /** + If supported by the platform and the type of DC, fetch the contents of the DC, or a subset of it, as a bitmap. + */ + wxBitmap GetAsBitmap(const wxRect *subrect = NULL) const; + + + 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; + +}; + + + +/** + @class wxDCClipper + + 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) + { + wxDCClipper clip(dc, rect); + // ... drawing functions here are affected by clipping rect ... + } + + void OtherFunction() + { + wxDC dc; + MyFunction(dc); + // ... drawing functions here are not affected by clipping rect ... + } + @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} + + @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, + wxDCBrushChanger +*/ +class wxDCClipper +{ +public: + //@{ + /** + Sets the clipping region to the specified region/coordinates. + + The clipping region is automatically unset when this object is destroyed. + */ + wxDCClipper(wxDC& dc, const wxRegion& region); + wxDCClipper(wxDC& dc, const wxRect& rect); + wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); + //@} + + /** + Destroys the clipping region associated with the DC passed to the ctor. + */ + ~wxDCClipper(); +}; + + +/** + @class wxDCBrushChanger + + wxDCBrushChanger is a small helper class for setting a brush on a wxDC + and unsetting it automatically in the destructor, restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, + wxDCClipper +*/ +class wxDCBrushChanger +{ +public: + /** + Sets @a brush on the given @a dc, storing the old one. + + @param dc + The DC where the brush must be temporary set. + @param brush + The brush to set. + */ + wxDCBrushChanger(wxDC& dc, const wxBrush& brush); + + /** + Restores the brush originally selected in the DC passed to the ctor. + */ + ~wxDCBrushChanger(); +}; + + +/** + @class wxDCPenChanger + + wxDCPenChanger is a small helper class for setting a pen on a wxDC + and unsetting it automatically in the destructor, restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger, + wxDCClipper +*/ +class wxDCPenChanger +{ +public: + /** + Sets @a pen on the given @a dc, storing the old one. + + @param dc + The DC where the pen must be temporary set. + @param pen + The pen to set. + */ + wxDCPenChanger(wxDC& dc, const wxPen& pen); + + /** + Restores the pen originally selected in the DC passed to the ctor. + */ + ~wxDCPenChanger(); +}; + + + +/** + @class wxDCTextColourChanger + + wxDCTextColourChanger is a small helper class for setting a foreground + text colour on a wxDC and unsetting it automatically in the destructor, + restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, + wxDCClipper +*/ +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. + + @param dc + The DC where the colour must be temporary set. + @param col + The colour to set. + */ + 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. + */ + ~wxDCTextColourChanger(); +}; + + + +/** + @class wxDCFontChanger + + wxDCFontChanger is a small helper class for setting a font on a wxDC and + unsetting it automatically in the destructor, restoring the previous one. + + @since 2.9.0 + + @library{wxcore} + @category{gdi} + + @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger, + wxDCClipper +*/ +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. + + @param dc + The DC where the font must be temporary set. + @param font + The font to set. + */ + wxDCFontChanger(wxDC& dc, const wxFont& font); + + /** + 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(); };