// Name: dc.h
// Purpose: interface of wxDC
// Author: wxWidgets team
-// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
wxMM_TWIPS,
/**
- Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
+ Each logical unit is a @e "printer point" i.e.\ 1/72 of an inch.
Equivalent to about 353 micrometers.
*/
wxMM_POINTS
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
Not supported by wxPerl.
@endWxPerlOnly
*/
- void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
+ void DrawPolygon(int n, const wxPoint points[], wxCoord xoffset = 0,
wxCoord yoffset = 0,
wxPolygonFillMode fill_style = wxODDEVEN_RULE);
/**
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
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,
wxPolygonFillMode fill_style = wxODDEVEN_RULE);
/**
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[]);
+ void DrawSpline(int n, const wxPoint points[]);
/**
@overload
- wxFLOOD_BORDER: The area to be flooded is bounded by the given
colour.
+ Currently this method is not implemented in wxOSX and does nothing
+ there.
+
@return @false if the operation failed.
@note The present implementation for non-Windows platforms may fail to
find colour borders if the pixels do not match the colour
exactly. However the function will still return @true.
+
+ @note This method shouldn't be used with wxPaintDC under non-Windows
+ platforms as it uses GetPixel() internally and this may give
+ wrong results, notably in wxGTK. If you need to flood fill
+ wxPaintDC, create a temporary wxMemoryDC, flood fill it and then
+ blit it to, or draw as a bitmap on, wxPaintDC. See the example of
+ doing this in the drawing sample and wxBufferedPaintDC class.
*/
bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
wxFloodFillStyle style = wxFLOOD_SURFACE);
/**
Gets the 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;
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.
@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,
//@{
/**
- 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.
+ Copy from a source DC to this DC.
+
+ 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.
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.
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
@note Setting a pixel can be done using DrawPoint().
- @beginWxPythonOnly
- The wxColour value is returned and is not required as a parameter.
- @endWxPythonOnly
+ @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;
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
In wxPerl there are two methods instead of a single overloaded
method:
bool IsOk() const;
/**
- Sets the x and y axis orientation (i.e., the direction from lowest to
+ 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.
void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
/**
- Sets the device origin (i.e., the origin in pixels after scaling has
+ 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.
*/
//@}
+
+ /**
+ @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;
/**
@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}
projects / wxWidgets.git / blobdiff