Detailed Description

A memory device context provides a means to draw graphics onto a bitmap.

When drawing in to a mono-bitmap, using wxWHITE, wxWHITE_PEN and wxWHITE_BRUSH will draw the background colour (i.e. 0) whereas all other colours will draw the foreground colour (i.e. 1).

A bitmap must be selected into the new memory DC before it may be used for anything. Typical usage is as follows:

// Create a memory DC
wxMemoryDC temp_dc;
temp_dc.SelectObject(test_bitmap);
// We can now draw into the memory DC...
// Copy from this DC to another DC.
old_dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0);

Note that the memory DC must be deleted (or the bitmap selected out of it) before a bitmap can be reselected into another memory DC.

And, before performing any other operations on the bitmap data, the bitmap must be selected out of the memory DC:

temp_dc.SelectObject(wxNullBitmap);

This happens automatically when wxMemoryDC object goes out of scope.

Library: wxCore

Category: Device Contexts

See Also: wxBitmap, wxDC

Public Member Functions
	wxMemoryDC ()
	Constructs a new memory device context.

	wxMemoryDC (wxDC *dc)
	Constructs a new memory device context having the same characteristics as the given existing device context.

	wxMemoryDC (wxBitmap &bitmap)
	Constructs a new memory device context and calls SelectObject() with the given bitmap.

void	SelectObject (wxBitmap &bitmap)
	Works exactly like SelectObjectAsSource() but this is the function you should use when you select a bitmap because you want to modify it, e.g.

void	SelectObjectAsSource (const wxBitmap &bitmap)
	Selects the given bitmap into the device context, to use as the memory bitmap.

Public Member Functions inherited from wxDC
void	CopyAttributes (const wxDC &dc)
	Copy attributes from another DC.

int	GetDepth () const
	Returns the depth (number of bits/pixel) of this DC.

wxPoint	GetDeviceOrigin () const
	Returns the current device origin.

wxRasterOperationMode	GetLogicalFunction () const
	Gets the current logical function.

wxMappingMode	GetMapMode () const
	Gets the current mapping mode for the device context.

bool	GetPixel (wxCoord x, wxCoord y, wxColour *colour) const
	Gets in colour the colour at the specified location.

wxSize	GetPPI () const
	Returns the resolution of the device in pixels per inch.

void	GetSize (wxCoord width, wxCoord height) const
	Gets the horizontal and vertical extent of this device context in device units.

wxSize	GetSize () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	GetSizeMM (wxCoord width, wxCoord height) const
	Returns the horizontal and vertical resolution in millimetres.

wxSize	GetSizeMM () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	GetUserScale (double x, double y) const
	Gets the current user scale factor.

bool	IsOk () const
	Returns true if the DC is ok to use.

void	SetAxisOrientation (bool xLeftRight, bool yBottomUp)
	Sets the x and y axis orientation (i.e. the direction from lowest to highest values on the axis).

void	SetDeviceOrigin (wxCoord x, wxCoord y)
	Sets the device origin (i.e. the origin in pixels after scaling has been applied).

void	SetLogicalFunction (wxRasterOperationMode function)
	Sets the current logical function for the device context.

void	SetMapMode (wxMappingMode mode)
	The mapping mode of the device context defines the unit of measurement used to convert logical units to device units.

void	SetPalette (const wxPalette &palette)
	If this is a window DC or memory DC, assigns the given palette to the window or bitmap associated with the DC.

void	SetUserScale (double xScale, double yScale)
	Sets the user scaling factor, useful for applications which require 'zooming'.

void *	GetHandle () 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.

wxBitmap	GetAsBitmap (const wxRect *subrect=NULL) 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.

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

wxCoord	DeviceToLogicalX (wxCoord x) const
	Convert device X coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.

wxCoord	DeviceToLogicalXRel (wxCoord x) const
	Convert device X coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.

wxCoord	DeviceToLogicalY (wxCoord y) const
	Converts device Y coordinate to logical coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.

wxCoord	DeviceToLogicalYRel (wxCoord y) const
	Convert device Y coordinate to relative logical coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.

wxCoord	LogicalToDeviceX (wxCoord x) const
	Converts logical X coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.

wxCoord	LogicalToDeviceXRel (wxCoord x) const
	Converts logical X coordinate to relative device coordinate, using the current mapping mode and user scale factor but ignoring the axis orientation.

wxCoord	LogicalToDeviceY (wxCoord y) const
	Converts logical Y coordinate to device coordinate, using the current mapping mode, user scale factor, device origin and axis orientation.

wxCoord	LogicalToDeviceYRel (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.

void	Clear ()
	Clears the device context using the current background brush.

void	DrawArc (wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd, wxCoord xc, wxCoord yc)
	Draws an arc from the given start to the given end point.

void	DrawArc (const wxPoint &ptStart, const wxPoint &ptEnd, const wxPoint &centre)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawBitmap (const wxBitmap &bitmap, wxCoord x, wxCoord y, bool useMask=false)
	Draw a bitmap on the device context at the specified point.

void	DrawBitmap (const wxBitmap &bmp, const wxPoint &pt, bool useMask=false)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawCheckMark (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
	Draws a check mark inside the given rectangle.

void	DrawCheckMark (const wxRect &rect)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawCircle (wxCoord x, wxCoord y, wxCoord radius)
	Draws a circle with the given centre and radius.

void	DrawCircle (const wxPoint &pt, wxCoord radius)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawEllipse (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
	Draws an ellipse contained in the rectangle specified either with the given top left corner and the given size or directly.

void	DrawEllipse (const wxPoint &pt, const wxSize &size)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawEllipse (const wxRect &rect)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawEllipticArc (wxCoord x, wxCoord y, wxCoord width, wxCoord height, double start, double end)
	Draws an arc of an ellipse.

void	DrawEllipticArc (const wxPoint &pt, const wxSize &sz, double sa, double ea)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawIcon (const wxIcon &icon, wxCoord x, wxCoord y)
	Draw an icon on the display (does nothing if the device context is PostScript).

void	DrawIcon (const wxIcon &icon, const wxPoint &pt)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawLabel (const wxString &text, const wxBitmap &bitmap, const wxRect &rect, int alignment=wxALIGN_LEFT\|wxALIGN_TOP, int indexAccel=-1, wxRect *rectBounding=NULL)
	Draw optional bitmap and the text into the given rectangle and aligns it as specified by alignment parameter; it also will emphasize the character with the given index if it is != -1 and return the bounding rectangle if required.

void	DrawLabel (const wxString &text, const wxRect &rect, int alignment=wxALIGN_LEFT\|wxALIGN_TOP, int indexAccel=-1)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawLine (wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2)
	Draws a line from the first point to the second.

void	DrawLine (const wxPoint &pt1, const wxPoint &pt2)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawLines (int n, const wxPoint points[], wxCoord xoffset=0, wxCoord yoffset=0)
	Draws lines using an array of points of size n adding the optional offset coordinate.

void	DrawLines (const wxPointList *points, wxCoord xoffset=0, wxCoord yoffset=0)
	This method uses a list of wxPoints, adding the optional offset coordinate.

void	DrawPoint (wxCoord x, wxCoord y)
	Draws a point using the color of the current pen.

void	DrawPoint (const wxPoint &pt)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawPolygon (int n, const wxPoint points[], wxCoord xoffset=0, wxCoord yoffset=0, wxPolygonFillMode fill_style=wxODDEVEN_RULE)
	Draws a filled polygon using an array of points of size n, adding the optional offset coordinate.

void	DrawPolygon (const wxPointList *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.

void	DrawPolyPolygon (int n, const int count[], const wxPoint points[], wxCoord xoffset=0, wxCoord yoffset=0, wxPolygonFillMode fill_style=wxODDEVEN_RULE)
	Draws two or more filled polygons using an array of points, adding the optional offset coordinates.

void	DrawRectangle (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
	Draws a rectangle with the given top left corner, and with the given size.

void	DrawRectangle (const wxPoint &pt, const wxSize &sz)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawRectangle (const wxRect &rect)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawRotatedText (const wxString &text, wxCoord x, wxCoord y, double angle)
	Draws the text rotated by angle degrees (positive angles are counterclockwise; the full angle is 360 degrees).

void	DrawRotatedText (const wxString &text, const wxPoint &point, double angle)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawRoundedRectangle (wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius)
	Draws a rectangle with the given top left corner, and with the given size.

void	DrawRoundedRectangle (const wxPoint &pt, const wxSize &sz, double radius)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawRoundedRectangle (const wxRect &rect, double radius)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawSpline (int n, const wxPoint points[])
	Draws a spline between all given points using the current pen.

void	DrawSpline (const wxPointList *points)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawSpline (wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, wxCoord y3)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DrawText (const wxString &text, wxCoord x, wxCoord y)
	Draws a text string at the specified point, using the current text font, and the current text foreground and background colours.

void	DrawText (const wxString &text, const wxPoint &pt)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	GradientFillConcentric (const wxRect &rect, const wxColour &initialColour, const wxColour &destColour)
	Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside.

void	GradientFillConcentric (const wxRect &rect, const wxColour &initialColour, const wxColour &destColour, const wxPoint &circleCenter)
	Fill the area specified by rect with a radial gradient, starting from initialColour at the centre of the circle and fading to destColour on the circle outside.

void	GradientFillLinear (const wxRect &rect, const wxColour &initialColour, const wxColour &destColour, wxDirection nDirection=wxRIGHT)
	Fill the area specified by rect with a linear gradient, starting from initialColour and eventually fading to destColour.

bool	FloodFill (wxCoord x, wxCoord y, const wxColour &colour, wxFloodFillStyle style=wxFLOOD_SURFACE)
	Flood fills the device context starting from the given point, using the current brush colour, and using a style:

bool	FloodFill (const wxPoint &pt, const wxColour &col, wxFloodFillStyle style=wxFLOOD_SURFACE)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	CrossHair (wxCoord x, wxCoord y)
	Displays a cross hair using the current pen.

void	CrossHair (const wxPoint &pt)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	DestroyClippingRegion ()
	Destroys the current clipping region so that none of the DC is clipped.

void	GetClippingBox (wxCoord x, wxCoord y, wxCoord width, wxCoord height) const
	Gets the rectangle surrounding the current clipping region.

void	SetClippingRegion (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
	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.

void	SetClippingRegion (const wxPoint &pt, const wxSize &sz)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	SetClippingRegion (const wxRect &rect)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void	SetDeviceClippingRegion (const wxRegion &region)
	Sets the clipping region for this device context.

wxCoord	GetCharHeight () const
	Gets the character height of the currently set font.

wxCoord	GetCharWidth () const
	Gets the average character width of the currently set font.

wxFontMetrics	GetFontMetrics () const
	Returns the various font characteristics.

void	GetMultiLineTextExtent (const wxString &string, wxCoord w, wxCoord h, wxCoord heightLine=NULL, const wxFont font=NULL) const
	Gets the dimensions of the string using the currently selected font.

wxSize	GetMultiLineTextExtent (const wxString &string) const
	Gets the dimensions of the string using the currently selected font.

bool	GetPartialTextExtents (const wxString &text, wxArrayInt &widths) const
	Fills the widths array with the widths from the beginning of text to the corresponding character of text.

void	GetTextExtent (const wxString &string, wxCoord w, wxCoord h, wxCoord descent=NULL, wxCoord externalLeading=NULL, const wxFont *font=NULL) const
	Gets the dimensions of the string using the currently selected font.

wxSize	GetTextExtent (const wxString &string) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

int	GetBackgroundMode () const
	Returns the current background mode: `wxPENSTYLE_SOLID` or `wxPENSTYLE_TRANSPARENT`.

const wxFont &	GetFont () const
	Gets the current font.

wxLayoutDirection	GetLayoutDirection () const
	Gets the current layout direction of the device context.

const wxColour &	GetTextBackground () const
	Gets the current text background colour.

const wxColour &	GetTextForeground () const
	Gets the current text foreground colour.

void	SetBackgroundMode (int mode)
	mode may be one of `wxPENSTYLE_SOLID` and `wxPENSTYLE_TRANSPARENT`.

void	SetFont (const wxFont &font)
	Sets the current font for the DC.

void	SetTextBackground (const wxColour &colour)
	Sets the current text background colour for the DC.

void	SetTextForeground (const wxColour &colour)
	Sets the current text foreground colour for the DC.

void	SetLayoutDirection (wxLayoutDirection dir)
	Sets the current layout direction for the device context.

void	CalcBoundingBox (wxCoord x, wxCoord y)
	Adds the specified point to the bounding box which can be retrieved with MinX(), MaxX() and MinY(), MaxY() functions.

wxCoord	MaxX () const
	Gets the maximum horizontal extent used in drawing commands so far.

wxCoord	MaxY () const
	Gets the maximum vertical extent used in drawing commands so far.

wxCoord	MinX () const
	Gets the minimum horizontal extent used in drawing commands so far.

wxCoord	MinY () const
	Gets the minimum vertical extent used in drawing commands so far.

void	ResetBoundingBox ()
	Resets the bounding box: after a call to this function, the bounding box doesn't contain anything.

bool	StartDoc (const wxString &message)
	Starts a document (only relevant when outputting to a printer).

void	StartPage ()
	Starts a document page (only relevant when outputting to a printer).

void	EndDoc ()
	Ends a document (only relevant when outputting to a printer).

void	EndPage ()
	Ends a document page (only relevant when outputting to a printer).

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.

bool	StretchBlit (wxCoord xdest, wxCoord ydest, wxCoord dstWidth, wxCoord dstHeight, wxDC *source, wxCoord xsrc, wxCoord ysrc, wxCoord srcWidth, wxCoord srcHeight, wxRasterOperationMode logicalFunc=wxCOPY, bool useMask=false, wxCoord xsrcMask=wxDefaultCoord, wxCoord ysrcMask=wxDefaultCoord)
	Copy from a source DC to this DC possibly changing the scale.

const wxBrush &	GetBackground () const
	Gets the brush used for painting the background.

const wxBrush &	GetBrush () const
	Gets the current brush.

const wxPen &	GetPen () const
	Gets the current pen.

void	SetBackground (const wxBrush &brush)
	Sets the current background brush for the DC.

void	SetBrush (const wxBrush &brush)
	Sets the current brush for the DC.

void	SetPen (const wxPen &pen)
	Sets the current pen for the DC.

bool	CanUseTransformMatrix () const
	Check if the use of transformation matrix is supported by the current system.

bool	SetTransformMatrix (const wxAffineMatrix2D &matrix)
	Set the transformation matrix.

wxAffineMatrix2D	GetTransformMatrix () const
	Return the transformation matrix used by this device context.

void	ResetTransformMatrix ()
	Revert the transformation matrix to identity matrix.

bool	CanDrawBitmap () const
	Does the DC support drawing bitmaps?

bool	CanGetTextExtent () const
	Does the DC support calculating the size required to draw text?

Public Member Functions inherited from wxObject
	wxObject ()
	Default ctor; initializes to NULL the internal reference data.

	wxObject (const wxObject &other)
	Copy ctor.

virtual	~wxObject ()
	Destructor.

virtual wxClassInfo *	GetClassInfo () const
	This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).

wxObjectRefData *	GetRefData () const
	Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.

bool	IsKindOf (const wxClassInfo *info) const
	Determines whether this class is a subclass of (or the same class as) the given class.

bool	IsSameAs (const wxObject &obj) const
	Returns true if this object has the same data pointer as obj.

void	Ref (const wxObject &clone)
	Makes this object refer to the data in clone.

void	SetRefData (wxObjectRefData *data)
	Sets the wxObject::m_refData pointer.

void	UnRef ()
	Decrements the reference count in the associated data, and if it is zero, deletes the data.

void	UnShare ()
	This is the same of AllocExclusive() but this method is public.

void	operator delete (void *buf)
	The delete operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

void *	operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
	The new operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

Additional Inherited Members
Protected Member Functions inherited from wxObject
void	AllocExclusive ()
	Ensure that this object's data is not shared with any other object.

virtual wxObjectRefData *	CreateRefData () const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.

virtual wxObjectRefData *	CloneRefData (const wxObjectRefData *data) const
	Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.

Protected Attributes inherited from wxObject
wxObjectRefData *	m_refData
	Pointer to an object which is the object's reference-counted data.

Constructor & Destructor Documentation

wxMemoryDC::wxMemoryDC ( )

Constructs a new memory device context.

Use the wxDC::IsOk() member to test whether the constructor was successful in creating a usable device context. Don't forget to select a bitmap into the DC before drawing on it.

wxMemoryDC::wxMemoryDC ( wxDC * dc )

Constructs a new memory device context having the same characteristics as the given existing device context.

This constructor creates a memory device context compatible with dc in wxMSW, the argument is ignored in the other ports. If dc is NULL, a device context compatible with the screen is created, just as with the default constructor.

wxMemoryDC::wxMemoryDC ( wxBitmap & bitmap )

Constructs a new memory device context and calls SelectObject() with the given bitmap.

Use the wxDC::IsOk() member to test whether the constructor was successful in creating a usable device context.

Member Function Documentation

void wxMemoryDC::SelectObject ( wxBitmap & bitmap )

Works exactly like SelectObjectAsSource() but this is the function you should use when you select a bitmap because you want to modify it, e.g.

drawing on this DC.

Using SelectObjectAsSource() when modifying the bitmap may incur some problems related to wxBitmap being a reference counted object (see Reference Counting).

Before using the updated bitmap data, make sure to select it out of context first either by selecting wxNullBitmap into the device context or destroying the device context entirely.

If the bitmap is already selected in this device context, nothing is done. If it is selected in another context, the function asserts and drawing on the bitmap won't work correctly.

See Also: wxDC::DrawBitmap()

void wxMemoryDC::SelectObjectAsSource ( const wxBitmap & bitmap )

Selects the given bitmap into the device context, to use as the memory bitmap.

Selecting the bitmap into a memory DC allows you to draw into the DC (and therefore the bitmap) and also to use wxDC::Blit() to copy the bitmap to a window. For this purpose, you may find wxDC::DrawIcon() easier to use instead.

If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the current bitmap is selected out of the device context, and the original bitmap restored, allowing the current bitmap to be destroyed safely.

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation