// 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
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
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:
- <ol>
- <li>Creates a temporary bitmap and copies the destination area into
- it.</li>
- <li>Copies the source area into the temporary bitmap using the
- specified logical function.</li>
- <li>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.</li>
- <li>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.</li>
- <li>ORs the temporary bitmap with the destination area.</li>
- <li>Deletes the temporary bitmap.</li>
- </ol>
- 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
- */
- bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
- wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
- int logicalFunc = wxCOPY, bool useMask = false,
- wxCoord xsrcMask = -1, wxCoord ysrcMask = -1);
-
- /**
- Adds the specified point to the bounding box which can be retrieved
- with MinX(), MaxX() and MinY(), MaxY() functions.
-
- @see ResetBoundingBox()
+ @name Coordinate conversion functions
*/
- void CalcBoundingBox(wxCoord x, wxCoord y);
+ //@{
/**
- Clears the device context using the current background brush.
+ Convert @e device X coordinate to logical coordinate, using the current
+ mapping mode, user scale factor, device origin and axis orientation.
*/
- void Clear();
+ wxCoord DeviceToLogicalX(wxCoord x) const;
/**
- Performs all necessary computations for given platform and context type
- after each change of scale and origin parameters. Usually called
- automatically internally after such changes.
+ 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.
*/
- virtual void ComputeScaleAndOrigin();
+ 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
@see SetTextForeground(), SetTextBackground(), wxMemoryDC
*/
void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
- bool transparent);
+ 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
@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
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
*/
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
*/
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,
+ void DrawLines(int n, const wxPoint points[], wxCoord xoffset = 0,
wxCoord yoffset = 0);
/**
This method uses a list of wxPoints, adding the optional offset
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);
*/
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
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);
+ void DrawPolygon(int n, const wxPoint points[], wxCoord xoffset = 0,
+ 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
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
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[],
+ void DrawPolyPolygon(int n, const int count[], const 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
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
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
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, const 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(int n, wxPoint points[]);
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
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
+ @note The current @ref GetLogicalFunction() "logical function" is
ignored by this function.
*/
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,
- 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);
+ 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.
@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,
wxCoord* h,
wxCoord* heightLine = NULL,
- wxFont* font = NULL) const;
+ const wxFont* font = NULL) const;
/**
Gets the dimensions of the string using the currently selected font.
@a string is the text string to measure, @e heightLine, if non @NULL,
@note This function works with both single-line and multi-line strings.
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+
@see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
*/
- const wxSize GetMultiLineTextExtent(const wxString& string) const;
+ wxSize GetMultiLineTextExtent(const wxString& string) const;
/**
Fills the @a widths array with the widths from the beginning of @a text
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()
*/
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()
- */
- const wxPen GetPen() const;
+ 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.
- /**
- Gets in @a colour the colour at the specified location. Not available
- for wxPostScriptDC or wxMetafileDC.
+ 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 Setting a pixel can be done using DrawPoint().
+ @note This function only works with single-line strings.
- @beginWxPythonOnly
- The wxColour value is returned and is not required as a parameter.
- @endWxPythonOnly
- */
- bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
+ @beginWxPerlOnly
+ In wxPerl this method is implemented as GetTextExtent(string,
+ font = undef) returning a 4-element list (width, height,
+ descent, externalLeading)
+ @endWxPerlOnly
- /**
- Returns the resolution of the device in pixels per inch.
+ @see wxFont, SetFont(), GetPartialTextExtents(),
+ GetMultiLineTextExtent()
*/
- wxSize GetPPI() const;
+ void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
+ wxCoord* descent = NULL,
+ wxCoord* externalLeading = NULL,
+ const wxFont* font = NULL) 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:
+ @overload
- @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
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
*/
- void GetSize(wxCoord* width, wxCoord* height) const;
- const wxSize GetSize() const;
+ wxSize GetTextExtent(const wxString& string) const;
+
//@}
- //@{
+
/**
- Returns the horizontal and vertical resolution in millimetres.
+ @name Text properties functions
*/
- void GetSizeMM(wxCoord* width, wxCoord* height) const;
- const wxSize GetSizeMM() const;
- //@}
+ //@{
/**
- Gets the current text background colour.
+ Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
- @see SetTextBackground()
+ @see SetBackgroundMode()
*/
- const wxColour GetTextBackground() const;
+ int GetBackgroundMode() 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
- 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).
-
- 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.
+ 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.
+ */
+ const wxFont& GetFont() const;
- 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 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.
- @note This function only works with single-line strings.
+ @see SetLayoutDirection()
+ */
+ wxLayoutDirection GetLayoutDirection() 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 current text background colour.
- @see wxFont, SetFont(), GetPartialTextExtents(),
- GetMultiLineTextExtent()
+ @see SetTextBackground()
*/
- void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
- wxCoord* descent = NULL,
- wxCoord* externalLeading = NULL,
- const wxFont* font = NULL) const;
- const wxSize GetTextExtent(const wxString& string) const;
- //@}
+ const wxColour& GetTextBackground() const;
/**
Gets the current text foreground colour.
@see SetTextForeground()
*/
- const wxColour GetTextForeground() const;
+ const wxColour& GetTextForeground() const;
/**
- Gets the current user scale factor.
-
- @see SetUserScale()
+ @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 GetUserScale(double x, double y);
+ void SetBackgroundMode(int mode);
- //@{
/**
- 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.
+ Sets the current font for the 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.
+ 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.
- @note Currently this function is very slow, don't use it for real-time
- drawing.
+ @see wxFont
*/
- 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);
- //@}
+ void SetFont(const wxFont& font);
/**
- 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.
+ Sets the current text background colour for the DC.
*/
- void GradientFillLinear(const wxRect& rect,
- const wxColour& initialColour,
- const wxColour& destColour,
- wxDirection nDirection = wxEAST);
+ void SetTextBackground(const wxColour& colour);
/**
- Returns @true if the DC is ok to use.
- */
- bool Ok();
+ Sets the current text foreground colour for the DC.
- /**
- Converts logical X coordinate to device coordinate, using the current
- mapping mode, user scale factor, device origin and axis orientation.
+ @see wxMemoryDC for the interpretation of colours when drawing into a
+ monochrome bitmap.
*/
- wxCoord LogicalToDeviceX(wxCoord x) const;
+ void SetTextForeground(const wxColour& colour);
/**
- 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.
+ 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()
*/
- wxCoord LogicalToDeviceXRel(wxCoord x) const;
+ void SetLayoutDirection(wxLayoutDirection dir);
+
+ //@}
+
/**
- Converts logical Y coordinate to device coordinate, using the current
- mapping mode, user scale factor, device origin and axis orientation.
+ @name Bounding box functions
*/
- wxCoord LogicalToDeviceY(wxCoord y) 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.
+ Adds the specified point to the bounding box which can be retrieved
+ with MinX(), MaxX() and MinY(), MaxY() functions.
+
+ @see ResetBoundingBox()
*/
- wxCoord LogicalToDeviceYRel(wxCoord y) const;
+ void CalcBoundingBox(wxCoord x, wxCoord y);
/**
Gets the maximum horizontal extent used in drawing commands so far.
*/
void ResetBoundingBox();
+ //@}
+
+
/**
- 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.
+ @name Page and document start/end functions
+ */
+ //@{
- @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.
- */
- 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
- operations for placing a graphic on a page.
+ Starts a document (only relevant when outputting to a printer).
+ @a message is a message to show while printing.
*/
- void SetDeviceOrigin(wxCoord x, wxCoord y);
+ bool StartDoc(const wxString& message);
/**
- 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
+ Starts a document page (only relevant when outputting to a printer).
*/
- void SetFont(const wxFont& font);
+ void StartPage();
/**
- 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()
+ Ends a document (only relevant when outputting to a printer).
*/
- void SetLayoutDirection(wxLayoutDirection dir);
+ void EndDoc();
/**
- 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.
+ Ends a document page (only relevant when outputting to a printer).
*/
- 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.
+ void EndPage();
- 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(int 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
+ @name Bit-Block Transfer operations (blit)
*/
- 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.
+ Copy from a source DC to this DC.
- @see wxMemoryDC for the interpretation of colours when drawing into a
- monochrome bitmap.
- */
- void SetPen(const wxPen& pen);
+ 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().
- /**
- Sets the current text background colour for the DC.
- */
- void SetTextBackground(const wxColour& colour);
+ 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.
- /**
- Sets the current text foreground colour for the DC.
+ @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:
+ <ol>
+ <li>Creates a temporary bitmap and copies the destination area into
+ it.</li>
+ <li>Copies the source area into the temporary bitmap using the
+ specified logical function.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>ORs the temporary bitmap with the destination area.</li>
+ <li>Deletes the temporary bitmap.</li>
+ </ol>
+ 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.
- @see wxMemoryDC for the interpretation of colours when drawing into a
- monochrome bitmap.
- */
- void SetTextForeground(const wxColour& colour);
+ @remarks There is partial support for Blit() in wxPostScriptDC, under X.
- /**
- Sets the user scaling factor, useful for applications which require
- 'zooming'.
+ @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
*/
- void SetUserScale(double xScale, double yScale);
+ 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);
/**
- 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 possibly changing the scale.
- /**
- Starts a document page (only relevant when outputting to a printer).
- */
- bool StartPage();
+ 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.
- /**
- 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.
+ 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.
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.
@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.
+ 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
- -1, xsrc and ysrc will be assumed for the mask source position.
- Currently only implemented on Windows.
+ 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.
- StretchBlit() is only implemented under wxMAC and wxMSW.
-
See wxMemoryDC for typical usage.
@since 2.9.0
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 = -1, wxCoord ysrcMask = -1);
+ 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;
+
+ /**
+ 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 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)
}
@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()
+ @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
+ wxDCBrushChanger
*/
class wxDCClipper
{
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, int x, int y, int w, int h);
+ 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();
};
projects / wxWidgets.git / blobdiff