phoenix_title wx.GraphicsContext

A wx.GraphicsContext instance is the object that is drawn upon.

It is created by a renderer using wx.GraphicsRenderer.CreateContext . This can be either directly using a renderer instance, or indirectly using the static convenience Create functions of wx.GraphicsContext that always delegate the task to the default renderer.

def OnPaint(self, event):

    # Create paint DC
    dc = wx.PaintDC(self)

    # Create graphics context from it
    gc = wx.GraphicsContext.Create(dc)

    if gc:

        # make a path that contains a circle and some lines
        gc.SetPen(wx.RED_PEN)
        path = gc.CreatePath()
        path.AddCircle(50.0, 50.0, 50.0)
        path.MoveToPoint(0.0, 50.0)
        path.AddLineToPoint(100.0, 50.0)
        path.MoveToPoint(50.0, 0.0)
        path.AddLineToPoint(50.0, 100.0)
        path.CloseSubpath()
        path.AddRectangle(25.0, 25.0, 50.0, 50.0)

        gc.StrokePath(path)

Note

For some renderers (like Direct2D or Cairo) processing of drawing operations may be deferred (Direct2D render target normally builds up a batch of rendering commands but defers processing of these commands, Cairo operates on a separate surface) so to make drawing results visible you need to update the content of the context by calling wx.GraphicsContext.Flush or by destroying the context.


class_hierarchy Class Hierarchy

Inheritance diagram for class GraphicsContext:

method_summary Methods Summary

BeginLayer

All rendering will be done into a fully transparent temporary context.

Clip

Sets the clipping region to the intersection of the given region and the previously set clipping region.

ConcatTransform

Concatenates the passed in transform with the current transform of this context.

Create

Creates a wx.GraphicsContext from a wx.Window.

CreateBitmap

Creates wx.GraphicsBitmap from an existing wx.Bitmap.

CreateBitmapFromImage

Creates wx.GraphicsBitmap from an existing wx.Image.

CreateBrush

Creates a native brush from a wx.Brush.

CreateFont

Creates a native graphics font from a wx.Font and a text colour.

CreateFromNative

Creates a wx.GraphicsContext from a native context.

CreateFromNativeWindow

Creates a wx.GraphicsContext from a native window.

CreateFromUnknownDC

Creates a wx.GraphicsContext from a DC of unknown specific type.

CreateLinearGradientBrush

Creates a native brush with a linear gradient.

CreateMatrix

Creates a native affine transformation matrix from the passed in values.

CreatePath

Creates a native graphics path which is initially empty.

CreatePen

Creates a native pen from a wx.Pen.

CreateRadialGradientBrush

Creates a native brush with a radial gradient.

CreateSubBitmap

Extracts a sub-bitmap from an existing bitmap.

DisableOffset

Helper to determine if a 0.5 offset should be applied for the drawing operation.

DrawBitmap

Draws the bitmap.

DrawEllipse

Draws an ellipse.

DrawIcon

Draws the icon.

DrawLines

Draws a polygon.

DrawPath

Draws the path by first filling and then stroking.

DrawRectangle

Draws a rectangle.

DrawRoundedRectangle

Draws a rounded rectangle.

DrawText

Draws text at the defined position.

EnableOffset

Indicates whether the context should try to offset for pixel boundaries.

EndDoc

Done with that document (relevant only for printing / pdf etc.)

EndLayer

Composites back the drawings into the context with the opacity given at the BeginLayer call.

EndPage

Ends the current page (relevant only for printing / pdf etc.)

FillPath

Fills the path with the current brush.

Flush

Make sure that the current content of this context is immediately visible.

GetAntialiasMode

Returns the current shape antialiasing mode.

GetClipBox

Returns bounding box of the current clipping region.

GetCompositionMode

Returns the current compositing operator.

GetDPI

Returns the resolution of the graphics context in device points per inch.

GetInterpolationQuality

Returns the current interpolation quality.

GetNativeContext

Returns the native context (CGContextRef for Core Graphics, Graphics pointer for GDIPlus and cairo_t pointer for cairo).

GetPartialTextExtents

Fills the widths array with the widths from the beginning of text to the corresponding character of text.

GetSize

Returns the size of the graphics context in device coordinates.

GetFullTextExtent

Gets the dimensions of the string using the currently selected font.

GetTransform

Gets the current transformation matrix of this context.

GetWindow

Returns the associated window if any.

OffsetEnabled

Helper to determine if a 0.5 offset should be applied for the drawing operation.

PopState

Sets current state of the context to the state saved by a preceding call to PushState and removes that state from the stack of saved states.

PushState

Push the current state (like transformations, clipping region and quality settings) of the context on a stack.

ResetClip

Resets the clipping to original shape.

Rotate

Rotates the current transformation matrix (in radians).

Scale

Scales the current transformation matrix.

SetAntialiasMode

Sets the antialiasing mode, returns True if it supported.

SetBrush

Sets the brush for filling paths.

SetCompositionMode

Sets the compositing operator, returns True if it supported.

SetFont

Sets the font for drawing text.

SetInterpolationQuality

Sets the interpolation quality, returns True if it is supported.

SetPen

Sets the pen used for stroking.

SetTransform

Sets the current transformation matrix of this context.

ShouldOffset

Helper to determine if a 0.5 offset should be applied for the drawing operation.

StartDoc

Begin a new document (relevant only for printing / pdf etc.) If there is a progress dialog, message will be shown.

StartPage

Opens a new page (relevant only for printing / pdf etc.) with the given size in points.

StrokeLine

Strokes a single line.

StrokeLineSegments

Stroke disconnected lines from begin to end points.

StrokeLines

Stroke lines connecting all the points.

StrokePath

Strokes along a path with the current pen.

Translate

Translates the current transformation matrix.


api Class API

class wx.GraphicsContext(GraphicsObject)

A GraphicsContext instance is the object that is drawn upon.


Methods

BeginLayer(self, opacity)

All rendering will be done into a fully transparent temporary context.

Layers can be nested by making balanced calls to BeginLayer /EndLayer().

Parameters

opacity (wx.Double) –



Clip(self, *args, **kw)

overload Overloaded Implementations:



Clip (self, region)

Sets the clipping region to the intersection of the given region and the previously set clipping region.

The clipping region is an area to which drawing is restricted.

Parameters

region (wx.Region) –

Note

  • Clipping region should be given in logical coordinates.

  • Calling this function can only make the clipping region smaller, never larger.

  • You need to call ResetClip first if you want to set the clipping region exactly to the region specified.

  • If resulting clipping region is empty, then all drawing upon the context is clipped out (all changes made by drawing operations are masked out).



Clip (self, x, y, w, h)

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

Parameters
  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –





ConcatTransform(self, matrix)

Concatenates the passed in transform with the current transform of this context.

Parameters

matrix (wx.GraphicsMatrix) –



static Create(*args, **kw)

overload Overloaded Implementations:



Create (window)

Creates a wx.GraphicsContext from a wx.Window.

Parameters

window (wx.Window) –

Return type

wx.GraphicsContext



Create (windowDC)

Creates a wx.GraphicsContext from a wx.WindowDC.

Parameters

windowDC (wx.WindowDC) –

Return type

wx.GraphicsContext



Create (memoryDC)

Creates a wx.GraphicsContext from a wx.MemoryDC.

Parameters

memoryDC (wx.MemoryDC) –

Return type

wx.GraphicsContext



Create (printerDC)

Creates a wx.GraphicsContext from a wx.PrinterDC.

Under GTK+, this will only work when using the GtkPrint printing backend which is available since GTK+ 2.10.

Parameters

printerDC (wx.PrinterDC) –

Return type

wx.GraphicsContext



Create (metaFileDC)

Creates a wx.GraphicsContext from a EnhMetaFileDC.

This function, as EnhMetaFileDC class itself, is only available only under MSW.

Parameters

metaFileDC (MetafileDC) –

Return type

wx.GraphicsContext



Create (image)

Creates a wx.GraphicsContext associated with a wx.Image.

The image specifies the size of the context as well as whether alpha is supported (if wx.Image.HasAlpha ) or not and the initial contents of the context. The image object must have a life time greater than that of the new context as the context copies its contents back to the image when it is destroyed.

Parameters

image (wx.Image) –

Return type

wx.GraphicsContext

New in version 2.9.3.



Create ()

Create a lightweight context that can be used only for measuring text.

Return type

wx.GraphicsContext



Create (autoPaintDC)

Return type

wx.GraphicsContext





CreateBitmap(self, bitmap)

Creates wx.GraphicsBitmap from an existing wx.Bitmap.

Returns an invalid NullGraphicsBitmap on failure.

Parameters

bitmap (wx.Bitmap) –

Return type

wx.GraphicsBitmap



CreateBitmapFromImage(self, image)

Creates wx.GraphicsBitmap from an existing wx.Image.

This method is more efficient than converting wx.Image to wx.Bitmap first and then calling CreateBitmap but otherwise has the same effect.

Returns an invalid NullGraphicsBitmap on failure.

Parameters

image (wx.Image) –

Return type

wx.GraphicsBitmap

New in version 2.9.3.



CreateBrush(self, brush)

Creates a native brush from a wx.Brush.

Parameters

brush (wx.Brush) –

Return type

wx.GraphicsBrush



CreateFont(self, *args, **kw)

overload Overloaded Implementations:



CreateFont (self, font, col=BLACK)

Creates a native graphics font from a wx.Font and a text colour.

Parameters
Return type

wx.GraphicsFont

Note

For Direct2D graphics fonts can be created from TrueType fonts only.



CreateFont (self, sizeInPixels, facename, flags=FONTFLAG_DEFAULT, col=BLACK)

Creates a font object with the specified attributes.

The use of overload taking wx.Font is preferred, see wx.GraphicsRenderer.CreateFont for more details.

Parameters
  • sizeInPixels (float) –

  • facename (string) –

  • flags (int) –

  • col (wx.Colour) –

Return type

wx.GraphicsFont

New in version 2.9.3.

Note

For Direct2D graphics fonts can be created from TrueType fonts only.





static CreateFromNative(context)

Creates a wx.GraphicsContext from a native context.

This native context must be a CGContextRef for Core Graphics, a Graphics pointer for GDIPlus, or a cairo_t pointer for cairo.

Parameters

context

Return type

wx.GraphicsContext



static CreateFromNativeWindow(window)

Creates a wx.GraphicsContext from a native window.

Parameters

window

Return type

wx.GraphicsContext



static CreateFromUnknownDC(dc)

Creates a wx.GraphicsContext from a DC of unknown specific type.

Creates a wx.GraphicsContext if dc is a supported type (i.e. has a corresponding Create method, e.g. wx.WindowDC or wx.MemoryDC). Returns None if the DC is unsupported.

This method is only useful as a helper in generic code that operates with wx.DC and doesn’t known its exact type. Use Create instead if you know that the DC is e.g. wx.WindowDC.

Parameters

dc (wx.DC) –

Return type

wx.GraphicsContext

New in version 4.1/wxWidgets-3.1.1.



CreateLinearGradientBrush(self, *args, **kw)

overload Overloaded Implementations:



CreateLinearGradientBrush (self, x1, y1, x2, y2, c1, c2, matrix=NullGraphicsMatrix)

Creates a native brush with a linear gradient.

The brush starts at (x1, y1) and ends at (x2, y2). Either just the start and end gradient colours (c1 and c2) or full set of gradient stops can be specified.

The version taking wx.GraphicsGradientStops is new in wxWidgets 2.9.1.

The matrix parameter was added in wxWidgets 3.1.3

Parameters
Return type

wx.GraphicsBrush



CreateLinearGradientBrush (self, x1, y1, x2, y2, stops, matrix=NullGraphicsMatrix)

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

Parameters
Return type

wx.GraphicsBrush





CreateMatrix(self, *args, **kw)

overload Overloaded Implementations:



CreateMatrix (self, a=1.0, b=0.0, c=0.0, d=1.0, tx=0.0, ty=0.0)

Creates a native affine transformation matrix from the passed in values.

The default parameters result in an identity matrix.

Parameters
  • a (wx.Double) –

  • b (wx.Double) –

  • c (wx.Double) –

  • d (wx.Double) –

  • tx (wx.Double) –

  • ty (wx.Double) –

Return type

wx.GraphicsMatrix



CreateMatrix (self, mat)

Creates a native affine transformation matrix from the passed generic one.

Parameters

mat (wx.AffineMatrix2DBase) –

Return type

wx.GraphicsMatrix

New in version 2.9.4.





CreatePath(self)

Creates a native graphics path which is initially empty.

Return type

wx.GraphicsPath



CreatePen(self, *args, **kw)

overload Overloaded Implementations:



CreatePen (self, pen)

Creates a native pen from a wx.Pen.

Prefer to use the overload taking wx.GraphicsPenInfo unless you already have a wx.Pen as constructing one only to pass it to this method is wasteful.

Parameters

pen (wx.Pen) –

Return type

wx.GraphicsPen



CreatePen (self, info)

Creates a native pen from a wx.GraphicsPenInfo.

Parameters

info (wx.GraphicsPenInfo) –

Return type

wx.GraphicsPen

New in version 4.1/wxWidgets-3.1.1.





CreateRadialGradientBrush(self, *args, **kw)

overload Overloaded Implementations:



CreateRadialGradientBrush (self, startX, startY, endX, endY, radius, oColor, cColor, matrix=NullGraphicsMatrix)

Creates a native brush with a radial gradient.

The brush originates at (startX, startY) and ends on a circle around (endX, endY) with the given radius.

The gradient may be specified either by its start and end colours oColor and cColor or by a full set of gradient stops.

The version taking wx.GraphicsGradientStops is new in wxWidgets 2.9.1.

The ability to apply a transformation matrix to the gradient was added in 3.1.3

Parameters
  • startX (wx.Double) –

  • startY (wx.Double) –

  • endX (wx.Double) –

  • endY (wx.Double) –

  • radius (wx.Double) –

  • oColor (wx.Colour) –

  • cColor (wx.Colour) –

  • matrix (wx.GraphicsMatrix) –

Return type

wx.GraphicsBrush



CreateRadialGradientBrush (self, startX, startY, endX, endY, radius, stops, matrix=NullGraphicsMatrix)

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

Parameters
Return type

wx.GraphicsBrush





CreateSubBitmap(self, bitmap, x, y, w, h)

Extracts a sub-bitmap from an existing bitmap.

Parameters
  • bitmap (wx.GraphicsBitmap) –

  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –

Return type

wx.GraphicsBitmap



DisableOffset(self)

Helper to determine if a 0.5 offset should be applied for the drawing operation.



DrawBitmap(self, *args, **kw)

overload Overloaded Implementations:



DrawBitmap (self, bmp, x, y, w, h)

Draws the bitmap.

In case of a mono bitmap, this is treated as a mask and the current brushed is used for filling.

Parameters
  • bmp (wx.GraphicsBitmap) –

  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –



DrawBitmap (self, bmp, x, y, w, h)

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

Parameters
  • bmp (wx.Bitmap) –

  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –





DrawEllipse(self, x, y, w, h)

Draws an ellipse.

Parameters
  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –



DrawIcon(self, icon, x, y, w, h)

Draws the icon.

Parameters
  • icon (wx.Icon) –

  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –



DrawLines(self, point2Ds, fillStyle=ODDEVEN_RULE)

Draws a polygon.



DrawPath(self, path, fillStyle=ODDEVEN_RULE)

Draws the path by first filling and then stroking.

Parameters


DrawRectangle(self, x, y, w, h)

Draws a rectangle.

Parameters
  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –



DrawRoundedRectangle(self, x, y, w, h, radius)

Draws a rounded rectangle.

Parameters
  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –

  • radius (wx.Double) –



DrawText(self, *args, **kw)

overload Overloaded Implementations:



DrawText (self, str, x, y)

Draws text at the defined position.

Parameters
  • str (string) –

  • x (wx.Double) –

  • y (wx.Double) –



DrawText (self, str, x, y, angle)

Draws text at the defined position.

Parameters
  • str (string) – The text to draw.

  • x (wx.Double) – The x coordinate position to draw the text at.

  • y (wx.Double) – The y coordinate position to draw the text at.

  • angle (wx.Double) – The angle relative to the (default) horizontal direction to draw the string.



DrawText (self, str, x, y, backgroundBrush)

Draws text at the defined position.

Parameters
  • str (string) – The text to draw.

  • x (wx.Double) – The x coordinate position to draw the text at.

  • y (wx.Double) – The y coordinate position to draw the text at.

  • backgroundBrush (wx.GraphicsBrush) – Brush to fill the text with.



DrawText (self, str, x, y, angle, backgroundBrush)

Draws text at the defined position.

Parameters
  • str (string) – The text to draw.

  • x (wx.Double) – The x coordinate position to draw the text at.

  • y (wx.Double) – The y coordinate position to draw the text at.

  • angle (wx.Double) – The angle relative to the (default) horizontal direction to draw the string.

  • backgroundBrush (wx.GraphicsBrush) – Brush to fill the text with.





EnableOffset(self, enable=True)

Indicates whether the context should try to offset for pixel boundaries.

This only makes sense on bitmap devices like screen. By default this is turned off.

Parameters

enable (bool) –



EndDoc(self)

Done with that document (relevant only for printing / pdf etc.)



EndLayer(self)

Composites back the drawings into the context with the opacity given at the BeginLayer call.



EndPage(self)

Ends the current page (relevant only for printing / pdf etc.)



FillPath(self, path, fillStyle=ODDEVEN_RULE)

Fills the path with the current brush.

Parameters


Flush(self)

Make sure that the current content of this context is immediately visible.



GetAntialiasMode(self)

Returns the current shape antialiasing mode.

Return type

wx.AntialiasMode



GetClipBox(self, x, y, w, h)

Returns bounding box of the current clipping region.

Parameters
  • x (wx.Double) –

  • y (wx.Double) –

  • w (wx.Double) –

  • h (wx.Double) –

New in version 4.1/wxWidgets-3.1.1.

Note

  • If clipping region is empty, then empty rectangle is returned (x, y, w, h are set to zero).



GetCompositionMode(self)

Returns the current compositing operator.

Return type

wx.CompositionMode



GetDPI(self)

Returns the resolution of the graphics context in device points per inch.

Return type

tuple

Returns

( dpiX, dpiY )



GetInterpolationQuality(self)

Returns the current interpolation quality.

Return type

wx.InterpolationQuality



GetNativeContext(self)

Returns the native context (CGContextRef for Core Graphics, Graphics pointer for GDIPlus and cairo_t pointer for cairo).



GetPartialTextExtents(self, text)

Fills the widths array with the widths from the beginning of text to the corresponding character of text.

Parameters

text (string) –

Return type

list of floats



GetSize(self)

Returns the size of the graphics context in device coordinates.

Return type

tuple

Returns

( width, height )



GetFullTextExtent(self, *args, **kw)

overload Overloaded Implementations:



GetFullTextExtent (self, text)

Gets the dimensions of the string using the currently selected font.

Parameters

text (string) – The text string to measure.

Return type

tuple

Returns

( width, height, descent, externalLeading )



GetFullTextExtent (self, text)

Gets the dimensions of the string using the currently selected font.

Return type

tuple

Returns

( width, height )





GetTransform(self)

Gets the current transformation matrix of this context.

Return type

wx.GraphicsMatrix



GetWindow(self)

Returns the associated window if any.

If this context was created using Create overload taking wx.Window or wx.WindowDC, this method returns the corresponding window. Otherwise returns None.

Return type

wx.Window

Returns

A possibly None window pointer.

New in version 4.1/wxWidgets-3.1.2.



OffsetEnabled(self)

Helper to determine if a 0.5 offset should be applied for the drawing operation.

Return type

bool



PopState(self)

Sets current state of the context to the state saved by a preceding call to PushState and removes that state from the stack of saved states.

See also

PushState



PushState(self)

Push the current state (like transformations, clipping region and quality settings) of the context on a stack.

Multiple balanced calls to PushState and PopState can be nested.

See also

PopState



ResetClip(self)

Resets the clipping to original shape.



Rotate(self, angle)

Rotates the current transformation matrix (in radians).

Parameters

angle (wx.Double) –



Scale(self, xScale, yScale)

Scales the current transformation matrix.

Parameters
  • xScale (wx.Double) –

  • yScale (wx.Double) –



SetAntialiasMode(self, antialias)

Sets the antialiasing mode, returns True if it supported.

Parameters

antialias (AntialiasMode) –

Return type

bool



SetBrush(self, *args, **kw)

Sets the brush for filling paths.

overload Overloaded Implementations:



SetBrush (self, brush)

Parameters

brush (wx.Brush) –



SetBrush (self, brush)

Parameters

brush (wx.GraphicsBrush) –





SetCompositionMode(self, op)

Sets the compositing operator, returns True if it supported.

Parameters

op (CompositionMode) –

Return type

bool



SetFont(self, *args, **kw)

overload Overloaded Implementations:



SetFont (self, font, colour)

Sets the font for drawing text.

Parameters

Note

For Direct2D only TrueType fonts can be used.



SetFont (self, font)

Sets the font for drawing text.

Parameters

font (wx.GraphicsFont) –





SetInterpolationQuality(self, interpolation)

Sets the interpolation quality, returns True if it is supported.

Parameters

interpolation (InterpolationQuality) –

Return type

bool

Note

Not implemented in Cairo backend currently.



SetPen(self, *args, **kw)

Sets the pen used for stroking.

overload Overloaded Implementations:



SetPen (self, pen)

Parameters

pen (wx.Pen) –



SetPen (self, pen)

Parameters

pen (wx.GraphicsPen) –





SetTransform(self, matrix)

Sets the current transformation matrix of this context.

Parameters

matrix (wx.GraphicsMatrix) –



ShouldOffset(self)

Helper to determine if a 0.5 offset should be applied for the drawing operation.

Return type

bool



StartDoc(self, message)

Begin a new document (relevant only for printing / pdf etc.) If there is a progress dialog, message will be shown.

Parameters

message (string) –

Return type

bool



StartPage(self, width=0, height=0)

Opens a new page (relevant only for printing / pdf etc.) with the given size in points.

(If both are null the default page size will be used.)

Parameters
  • width (wx.Double) –

  • height (wx.Double) –



StrokeLine(self, x1, y1, x2, y2)

Strokes a single line.

Parameters
  • x1 (wx.Double) –

  • y1 (wx.Double) –

  • x2 (wx.Double) –

  • y2 (wx.Double) –



StrokeLineSegments(self, beginPoint2Ds, endPoint2Ds)

Stroke disconnected lines from begin to end points.



StrokeLines(self, point2Ds)

Stroke lines connecting all the points.



StrokePath(self, path)

Strokes along a path with the current pen.

Parameters

path (wx.GraphicsPath) –



Translate(self, dx, dy)

Translates the current transformation matrix.

Parameters
  • dx (wx.Double) –

  • dy (wx.Double) –


Properties

AntialiasMode

See GetAntialiasMode and SetAntialiasMode



CompositionMode

See GetCompositionMode and SetCompositionMode



InterpolationQuality

See GetInterpolationQuality and SetInterpolationQuality



NativeContext

See GetNativeContext



TextExtent

See GetTextExtent



Transform

See GetTransform and SetTransform



Window

See GetWindow