/////////////////////////////////////////////////////////////////////////////

// Name: _dc.i

// Purpose: SWIG interface defs for wxDC and releated classes

//

// Author: Robin Dunn

//

// Created: 7-July-1997

// RCS-ID: $Id$

// Copyright: (c) 2003 by Total Control Software

// Licence: wxWindows license

/////////////////////////////////////////////////////////////////////////////

// Not a %module

//---------------------------------------------------------------------------

%{

#include "wx/wxPython/pydrawxxx.h"

#include <wx/dcgraph.h>

%}

// TODO: 1. wrappers for wxDrawObject and wxDC::DrawObject

// 2. Do the factory and wxDCImpl classes need to be exposed?

//---------------------------------------------------------------------------

%newgroup;

class wxDCImpl;

// Logical ops

enum wxRasterOperationMode

{

wxCLEAR, // 0

wxXOR, // src XOR dst

wxINVERT, // NOT dst

wxOR_REVERSE, // src OR (NOT dst)

wxAND_REVERSE, // src AND (NOT dst)

wxCOPY, // src

wxAND, // src AND dst

wxAND_INVERT, // (NOT src) AND dst

wxNO_OP, // dst

wxNOR, // (NOT src) AND (NOT dst)

wxEQUIV, // (NOT src) XOR dst

wxSRC_INVERT, // (NOT src)

wxOR_INVERT, // (NOT src) OR dst

wxNAND, // (NOT src) OR (NOT dst)

wxOR, // src OR dst

wxSET // 1

// We never had these in wxPython, and it looks like they are going away

// so don't bother with them...

// #if WXWIN_COMPATIBILITY_2_8

// ,wxROP_BLACK = wxCLEAR,

// wxBLIT_BLACKNESS = wxCLEAR,

// wxROP_XORPEN = wxXOR,

// wxBLIT_SRCINVERT = wxXOR,

// wxROP_NOT = wxINVERT,

// wxBLIT_DSTINVERT = wxINVERT,

// wxROP_MERGEPENNOT = wxOR_REVERSE,

// wxBLIT_00DD0228 = wxOR_REVERSE,

// wxROP_MASKPENNOT = wxAND_REVERSE,

// wxBLIT_SRCERASE = wxAND_REVERSE,

// wxROP_COPYPEN = wxCOPY,

// wxBLIT_SRCCOPY = wxCOPY,

// wxROP_MASKPEN = wxAND,

// wxBLIT_SRCAND = wxAND,

// wxROP_MASKNOTPEN = wxAND_INVERT,

// wxBLIT_00220326 = wxAND_INVERT,

// wxROP_NOP = wxNO_OP,

// wxBLIT_00AA0029 = wxNO_OP,

// wxROP_NOTMERGEPEN = wxNOR,

// wxBLIT_NOTSRCERASE = wxNOR,

// wxROP_NOTXORPEN = wxEQUIV,

// wxBLIT_00990066 = wxEQUIV,

// wxROP_NOTCOPYPEN = wxSRC_INVERT,

// wxBLIT_NOTSCRCOPY = wxSRC_INVERT,

// wxROP_MERGENOTPEN = wxOR_INVERT,

// wxBLIT_MERGEPAINT = wxOR_INVERT,

// wxROP_NOTMASKPEN = wxNAND,

// wxBLIT_007700E6 = wxNAND,

// wxROP_MERGEPEN = wxOR,

// wxBLIT_SRCPAINT = wxOR,

// wxROP_WHITE = wxSET,

// wxBLIT_WHITENESS = wxSET

// #endif //WXWIN_COMPATIBILITY_2_8

};

// Flood styles

enum wxFloodFillStyle

{

wxFLOOD_SURFACE = 1,

wxFLOOD_BORDER

};

// Mapping modes (same values as used by Windows, don't change)

enum wxMappingMode

{

wxMM_TEXT = 1,

wxMM_TWIPS,

wxMM_POINTS,

wxMM_METRIC

};

struct wxFontMetrics

{

wxFontMetrics();

~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".

};

//---------------------------------------------------------------------------

DocStr(wxDC,

"A wx.DC is a device context onto which graphics and text can be

drawn. It is intended to represent a number of output devices in a

generic way, so a window can have a device context associated with it,

and a printer also has a device context. In this way, the same piece

of code may write to a number of different devices, if the device

context is used as a parameter.

Derived types of wxDC have documentation for specific features only,

so refer to this section for most device context information.

The wx.DC class is abstract and can not be instantiated, you must use

one of the derived classes instead. Which one will depend on the

situation in which it is used.", "");

class wxDC : public wxObject {

public:

// wxDC(); **** abstract base class, can't instantiate.

~wxDC();

%pythoncode {

%# These have been deprecated in wxWidgets. Since they never

%# really did anything to begin with, just make them be NOPs.

def BeginDrawing(self): pass

def EndDrawing(self): pass

}

wxDCImpl *GetImpl();

wxWindow *GetWindow();

// TODO virtual void DrawObject(wxDrawObject* drawobject);

// copy attributes (font, colours and writing direction) from another DC

void CopyAttributes(const wxDC& dc);

DocStr(

FloodFill,

"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.

Returns 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.", "");

bool FloodFill(wxCoord x, wxCoord y, const wxColour& col, wxFloodFillStyle style = wxFLOOD_SURFACE);

%Rename(FloodFillPoint, bool, FloodFill(const wxPoint& pt, const wxColour& col, wxFloodFillStyle style = wxFLOOD_SURFACE));

// fill the area specified by rect with a radial gradient, starting from

// initialColour in the centre of the cercle and fading to destColour.

DocDeclStr(

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 in the center of the circle and fading to destColour on

the outside of the circle. The circleCenter argument is the relative

coordinants of the center of the circle in the specified rect.

Note: Currently this function is very slow, don't use it for real-time

drawing.", "");

DocDeclStr(

void , GradientFillLinear(const wxRect& rect,

const wxColour& initialColour,

const wxColour& destColour,

wxDirection nDirection = wxEAST),

"Fill the area specified by rect with a linear gradient, starting from

initialColour and eventually fading to destColour. The nDirection

parameter specifies the direction of the colour change, default is to

use initialColour on the left part of the rectangle and destColour on

the right side.", "");

DocStr(

GetPixel,

"Gets the colour at the specified location on the DC.","");

%extend {

wxColour GetPixel(wxCoord x, wxCoord y) {

wxColour col;

self->GetPixel(x, y, &col);

return col;

}

wxColour GetPixelPoint(const wxPoint& pt) {

wxColour col;

self->GetPixel(pt, &col);

return col;

}

}

DocStr(

DrawLine,

"Draws a line from the first point to the second. The current pen is

used for drawing the line. Note that the second point is *not* part of

the line and is not drawn by this function (this is consistent with

the behaviour of many other toolkits).", "");

void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);

%Rename(DrawLinePoint, void, DrawLine(const wxPoint& pt1, const wxPoint& pt2));

DocStr(

CrossHair,

"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.", "");

void CrossHair(wxCoord x, wxCoord y);

%Rename(CrossHairPoint, void, CrossHair(const wxPoint& pt));

DocStr(

DrawArc,

"Draws an arc of a circle, centred on the *center* point (xc, yc), from

the first point to the second. The current pen is used for the outline

and the current brush for filling the shape.

The arc is drawn in an anticlockwise direction from the start point to

the end point.", "");

void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc);

%Rename(DrawArcPoint, void, DrawArc(const wxPoint& pt1, const wxPoint& pt2, const wxPoint& center));

DocStr(

DrawCheckMark,

"Draws a check mark inside the given rectangle.", "");

void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

%Rename(DrawCheckMarkRect, void, DrawCheckMark(const wxRect& rect));

DocStr(

DrawEllipticArc,

"Draws an arc of an ellipse, with the given rectangle defining the

bounds of the ellipse. The current pen is used for drawing the arc and

the current brush is used for drawing the pie.

The *start* and *end* parameters specify the start and end of the arc

relative to the three-o'clock position from the center of the

rectangle. Angles are specified in degrees (360 is a complete

circle). Positive values mean counter-clockwise motion. If start is

equal to end, a complete ellipse will be drawn.", "");

void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord w, wxCoord h, double start, double end);

%Rename(DrawEllipticArcPointSize, void, DrawEllipticArc(const wxPoint& pt, const wxSize& sz, double start, double end));

DocStr(

DrawPoint,

"Draws a point using the current pen.", "");

void DrawPoint(wxCoord x, wxCoord y);

%Rename(DrawPointPoint, void, DrawPoint(const wxPoint& pt));

DocStr(

DrawRectangle,

"Draws a rectangle with the given top left corner, and with the given

size. The current pen is used for the outline and the current brush

for filling the shape.", "");

void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

%Rename(DrawRectangleRect,void, DrawRectangle(const wxRect& rect));

%Rename(DrawRectanglePointSize, void, DrawRectangle(const wxPoint& pt, const wxSize& sz));

DocStr(

DrawRoundedRectangle,

"Draws a rectangle with the given top left corner, and with the given

size. The corners are quarter-circles using the given radius. The

current pen is used for the outline and the current brush for filling

the shape.

If radius is positive, the value is assumed to be the radius of the

rounded corner. If radius is negative, the absolute value is assumed

to be the proportion of the smallest dimension of the rectangle. This

means that the corner can be a sensible size relative to the size of

the rectangle, and also avoids the strange effects X produces when the

corners are too big for the rectangle.", "");

void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius);

%Rename(DrawRoundedRectangleRect, void, DrawRoundedRectangle(const wxRect& r, double radius));

%Rename(DrawRoundedRectanglePointSize, void, DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, double radius));

DocStr(

DrawCircle,

"Draws a circle with the given center point and radius. The current

pen is used for the outline and the current brush for filling the

shape.", "

:see: `DrawEllipse`");

void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);

%Rename(DrawCirclePoint, void, DrawCircle(const wxPoint& pt, wxCoord radius));

DocStr(

DrawEllipse,

"Draws an ellipse contained in the specified rectangle. The current pen

is used for the outline and the current brush for filling the shape.", "

:see: `DrawCircle`");

void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

%Rename(DrawEllipseRect, void, DrawEllipse(const wxRect& rect));

%Rename(DrawEllipsePointSize, void, DrawEllipse(const wxPoint& pt, const wxSize& sz));

DocStr(

DrawIcon,

"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

window.", "");

void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);

%Rename(DrawIconPoint, void, DrawIcon(const wxIcon& icon, const wxPoint& pt));

DocStr(

DrawBitmap,

"Draw a bitmap on the device context at the specified point. If

*transparent* is true and the bitmap has a transparency mask, (or

alpha channel on the platforms that support it) then the bitmap will

be drawn transparently.", "

When drawing a mono-bitmap, the current text foreground colour will be

used to draw the foreground of the bitmap (all bits set to 1), and the

current text background colour to draw the background (all bits set to

0).

:see: `SetTextForeground`, `SetTextBackground` and `wx.MemoryDC`");

void DrawBitmap(const wxBitmap &bmp, wxCoord x, wxCoord y, bool useMask = false);

%Rename(DrawBitmapPoint, void, DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, bool useMask = false));

DocStr(

DrawText,

"Draws a text string at the specified point, using the current text

font, and the current text foreground and background colours.

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.

**NOTE**: under wxGTK the current logical function is used by this

function but it is ignored by wxMSW. Thus, you should avoid using

logical functions with this function in portable programs.", "

:see: `DrawRotatedText`");

void DrawText(const wxString& text, wxCoord x, wxCoord y);

%Rename(DrawTextPoint, void, DrawText(const wxString& text, const wxPoint& pt));

DocStr(

DrawRotatedText,

"Draws the text rotated by *angle* degrees, if supported by the platform.

**NOTE**: Under Win9x only TrueType fonts can be drawn by this

function. In particular, a font different from ``wx.NORMAL_FONT``

should be used as the it is not normally a TrueType

font. ``wx.SWISS_FONT`` is an example of a font which is.","

:see: `DrawText`");

void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle);

%Rename(DrawRotatedTextPoint, void, DrawRotatedText(const wxString& text, const wxPoint& pt, double angle));

DocDeclStr(

bool , Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,

wxDC *source, wxCoord xsrc, wxCoord ysrc,

wxRasterOperationMode rop = wxCOPY, bool useMask = false,

wxCoord xsrcMask = -1, wxCoord ysrcMask = -1),

"Copy from a source DC to this DC. Parameters specify 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 rop: 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.

: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.

:param ysrcMask: Source y position on the mask.

");

DocDeclStrName(

bool , Blit(const wxPoint& destPt, const wxSize& sz,

wxDC *source, const wxPoint& srcPt,

wxRasterOperationMode rop = wxCOPY, bool useMask = false,

const wxPoint& srcPtMask = wxDefaultPosition),

"Copy from a source DC to this DC. Parameters specify 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 destPt: Destination device context position.

:param sz: Size of source area to be copied.

:param source: Source device context.

:param srcPt: Source device context position.

:param rop: 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.

:param srcPtMask: Source position on the mask.

",

BlitPointSize);

DocDeclStr(

bool , StretchBlit(wxCoord dstX, wxCoord dstY,

wxCoord dstWidth, wxCoord dstHeight,

wxDC *source,

wxCoord srcX, wxCoord srcY,

wxCoord srcWidth, wxCoord srcHeight,

wxRasterOperationMode rop = wxCOPY, bool useMask = false,

wxCoord srcMaskX = wxDefaultCoord,

wxCoord srcMaskY = 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.", "

:param xdest: Destination device context x position.

:param ydest: Destination device context y position.

:param dstWidth: Width of destination area.

:param dstHeight: Height of destination area.

:param source: Source device context.

:param xsrc: Source device context x position.

:param ysrc: Source device context y position.

:param srcWidth: Width of source area to be copied.

:param srcHeight: Height of source area to be copied.

:param logicalFunc: Logical function to use: see `SetLogicalFunction`.

:param useMask: If true, StretchBlit does a transparent blit using

the mask that is associated with the bitmap selected

into the source device context.

: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.

");

DocDeclStrName(

bool , StretchBlit(const wxPoint& dstPt, const wxSize& dstSize,

wxDC *source, const wxPoint& srcPt, const wxSize& srcSize,

wxRasterOperationMode rop = wxCOPY, bool useMask = false,

const wxPoint& srcMaskPt = wxDefaultPosition),

"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. This version is the same as `StretchBlit`

except `wx.Point` and `wx.Size` objects are used instead of individual

position and size components.", "",

StretchBlitPointSize);

DocDeclStr(

wxBitmap , GetAsBitmap(const wxRect *subrect = NULL) const,

"", "");

DocStr(

SetClippingRegion,

"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`, `wx.Region`");

void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

%Rename(SetClippingRegionPointSize, void, SetClippingRegion(const wxPoint& pt, const wxSize& sz));

%Rename(SetClippingRegionAsRegion, void, SetClippingRegion(const wxRegion& region));

%Rename(SetClippingRect, void, SetClippingRegion(const wxRect& rect));

DocDeclStr(

void , SetDeviceClippingRegion(const wxRegion& region),

"The coordinates of the region used in this method one are in device

coordinates, not the logical ones", "");

DocDeclAStr(

void , DrawLines(int points, wxPoint* points_array,

wxCoord xoffset = 0, wxCoord yoffset = 0),

"DrawLines(self, List points, int xoffset=0, int yoffset=0)",

"Draws lines using a sequence of `wx.Point` objects, adding the

optional offset coordinate. The current pen is used for drawing the

lines.", "");

DocDeclAStr(

void , DrawPolygon(int points, wxPoint* points_array,

wxCoord xoffset = 0, wxCoord yoffset = 0,

wxPolygonFillMode fillStyle = wxODDEVEN_RULE),

"DrawPolygon(self, List points, int xoffset=0, int yoffset=0,

wxPolygonFillMode fillStyle=ODDEVEN_RULE)",

"Draws a filled polygon using a sequence of `wx.Point` objects, adding

the optional offset coordinate. The last argument specifies the fill

rule: ``wx.ODDEVEN_RULE`` (the default) or ``wx.WINDING_RULE``.

The current pen is used for drawing the outline, and the current brush

for filling the shape. Using a transparent brush suppresses

filling. Note that wxWidgets automatically closes the first and last

points.", "");

// TODO: Figure out a good typemap for this...

// Convert the first 3 args from a sequence of sequences?

// void DrawPolyPolygon(int n, int count[], wxPoint points[],

// wxCoord xoffset = 0, wxCoord yoffset = 0,

// int fillStyle = wxODDEVEN_RULE);

DocDeclStr(

void , DrawLabel(const wxString& text, const wxRect& rect,

int alignment = wxALIGN_LEFT | wxALIGN_TOP,

int indexAccel = -1),

"Draw *text* within the specified rectangle, abiding by the alignment

flags. Will additionally emphasize the character at *indexAccel* if

it is not -1.", "

:see: `DrawImageLabel`");

%extend {

DocStr(DrawImageLabel,

"Draw *text* and an image (which may be ``wx.NullBitmap`` to skip

drawing it) within the specified rectangle, abiding by the alignment

flags. Will additionally emphasize the character at *indexAccel* if

it is not -1. Returns the bounding rectangle.", "");

wxRect DrawImageLabel(const wxString& text,

const wxBitmap& image,

const wxRect& rect,

int alignment = wxALIGN_LEFT | wxALIGN_TOP,

int indexAccel = -1) {

wxRect rv;

self->DrawLabel(text, image, rect, alignment, indexAccel, &rv);

return rv;

}

}

DocDeclAStr(

void , DrawSpline(int points, wxPoint* points_array),

"DrawSpline(self, List points)",

"Draws a spline between all given control points, (a list of `wx.Point`

objects) using the current pen. The spline is drawn using a series of

lines, using an algorithm taken from the X drawing program 'XFIG'.", "");

// global DC operations

// --------------------

DocDeclStr(

virtual void , Clear(),

"Clears the device context using the current background brush.", "");

DocDeclStr(

virtual bool , StartDoc(const wxString& message),

"Starts a document (only relevant when outputting to a

printer). *Message* is a message to show whilst printing.", "");

DocDeclStr(

virtual void , EndDoc(),

"Ends a document (only relevant when outputting to a printer).", "");

DocDeclStr(

virtual void , StartPage(),

"Starts a document page (only relevant when outputting to a printer).", "");

DocDeclStr(

virtual void , EndPage(),

"Ends a document page (only relevant when outputting to a printer).", "");

// set objects to use for drawing

// ------------------------------

DocDeclStr(

virtual void , SetFont(const wxFont& font),

"Sets the current font for the DC. It must be a valid font, in

particular you should not pass ``wx.NullFont`` to this method.","

:see: `wx.Font`");

DocDeclStr(

virtual void , SetPen(const wxPen& pen),

"Sets the current pen for the DC.

If the argument is ``wx.NullPen``, the current pen is selected out of the

device context, and the original pen restored.", "

:see: `wx.Pen`");

DocDeclStr(

virtual void , SetBrush(const wxBrush& brush),

"Sets the current brush for the DC.

If the argument is ``wx.NullBrush``, the current brush is selected out

of the device context, and the original brush restored, allowing the

current brush to be destroyed safely.","

:see: `wx.Brush`");

DocDeclStr(

virtual void , SetBackground(const wxBrush& brush),

"Sets the current background brush for the DC.", "");

DocDeclStr(

virtual void , SetBackgroundMode(int mode),

"*mode* may be one of ``wx.SOLID`` and ``wx.TRANSPARENT``. This setting

determines whether text will be drawn with a background colour or

not.", "");

DocDeclStr(

virtual 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. If the argument is

``wx.NullPalette``, the current palette is selected out of the device

context, and the original palette restored.", "

:see: `wx.Palette`");

DocDeclStr(

virtual void , DestroyClippingRegion(),

"Destroys the current clipping region so that none of the DC is

clipped.", "

:see: `SetClippingRegion`");

DocDeclAStr(

void, GetClippingBox(wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT) const,

"GetClippingBox() -> (x, y, width, height)",

"Gets the rectangle surrounding the current clipping region.", "");

%extend {

DocStr(

GetClippingRect,

"Gets the rectangle surrounding the current clipping region.", "");

wxRect GetClippingRect() {

wxRect rect;

self->GetClippingBox(rect);

return rect;

}

}

// text extent

// -----------

DocDeclStr(

virtual wxCoord , GetCharHeight() const,

"Gets the character height of the currently set font.", "");

DocDeclStr(

virtual wxCoord , GetCharWidth() const,

"Gets the average character width of the currently set font.", "");

wxFontMetrics GetFontMetrics() const;

DocDeclAStr(

void, GetTextExtent(const wxString& string, wxCoord *OUTPUT, wxCoord *OUTPUT),

"GetTextExtent(wxString string) -> (width, height)",

"Get the width and height of the text using the current font. Only

works for single line strings.", "");

DocDeclAStrName(

void, GetTextExtent(const wxString& string,

wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord* OUTPUT,

const wxFont* font = NULL),

"GetFullTextExtent(wxString string, Font font=None) ->\n (width, height, descent, externalLeading)",

"Get the width, height, decent and leading of the text using the

current or specified font. Only works for single line strings.", "",

GetFullTextExtent);

// works for single as well as multi-line strings

DocDeclAStr(

void, GetMultiLineTextExtent(const wxString& text,

wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT,

const wxFont *font = NULL),

"GetMultiLineTextExtent(wxString string, Font font=None) ->\n (width, height, lineHeight)",

"Get the width, height, and line height of the text using the

current or specified font. Works for single as well as multi-line

strings.", "");

%extend {

DocAStr(GetPartialTextExtents,

"GetPartialTextExtents(self, text) -> [widths]",

"Returns a list of integers such that each value is the distance in

pixels from the begining of text to the coresponding character of

*text*. The generic version simply builds a running total of the widths

of each character using GetTextExtent, however if the various

platforms have a native API function that is faster or more accurate

than the generic implementation then it will be used instead.", "");

wxArrayInt GetPartialTextExtents(const wxString& text) {

wxArrayInt widths;

self->GetPartialTextExtents(text, widths);

return widths;

}

}

// size and resolution

// -------------------

DocStr(

GetSize,

"This gets the horizontal and vertical resolution in device units. It

can be used to scale graphics to fit the page. For example, if *maxX*

and *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::

w, h = dc.GetSize()

scaleX = maxX*1.0 / w

scaleY = maxY*1.0 / h

dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY))

", "");

wxSize GetSize();

DocDeclAName(

void, GetSize( int *OUTPUT, int *OUTPUT ),

"GetSizeTuple() -> (width, height)",

GetSizeTuple);

DocStr(GetSizeMM, "Get the DC size in milimeters.", "");

wxSize GetSizeMM() const;

DocDeclAName(

void, GetSizeMM( int *OUTPUT, int *OUTPUT ) const,

"GetSizeMMTuple() -> (width, height)",

GetSizeMMTuple);

int GetResolution();

// coordinates conversions

// -----------------------

DocDeclStr(

wxCoord , DeviceToLogicalX(wxCoord x) const,

"Convert device X coordinate to logical coordinate, using the current

mapping mode.", "");

DocDeclStr(

wxCoord , DeviceToLogicalY(wxCoord y) const,

"Converts device Y coordinate to logical coordinate, using the current

mapping mode.", "");

DocDeclStr(

wxCoord , DeviceToLogicalXRel(wxCoord x) const,

"Convert device X coordinate to relative logical coordinate, using the

current mapping mode but ignoring the x axis orientation. Use this

function for converting a width, for example.", "");

DocDeclStr(

wxCoord , DeviceToLogicalYRel(wxCoord y) const,

"Convert device Y coordinate to relative logical coordinate, using the

current mapping mode but ignoring the y axis orientation. Use this

function for converting a height, for example.", "");

DocDeclStr(

wxCoord , LogicalToDeviceX(wxCoord x) const,

"Converts logical X coordinate to device coordinate, using the current

mapping mode.", "");

DocDeclStr(

wxCoord , LogicalToDeviceY(wxCoord y) const,

"Converts logical Y coordinate to device coordinate, using the current

mapping mode.", "");

DocDeclStr(

wxCoord , LogicalToDeviceXRel(wxCoord x) const,

"Converts logical X coordinate to relative device coordinate, using the

current mapping mode but ignoring the x axis orientation. Use this for

converting a width, for example.", "");

DocDeclStr(

wxCoord , LogicalToDeviceYRel(wxCoord y) const,

"Converts logical Y coordinate to relative device coordinate, using the

current mapping mode but ignoring the y axis orientation. Use this for

converting a height, for example.", "");

// query DC capabilities

// ---------------------

virtual bool CanDrawBitmap() const;

virtual bool CanGetTextExtent() const;

DocDeclStr(

virtual int , GetDepth() const,

"Returns the colour depth of the DC.", "");

DocDeclStr(

virtual wxSize , GetPPI() const,

"Resolution in pixels per inch", "");

DocDeclStr(

virtual bool , IsOk() const,

"Returns true if the DC is ok to use.", "");

%pythoncode { Ok = IsOk }

DocDeclStr(

int , GetBackgroundMode() const,

"Returns the current background mode, either ``wx.SOLID`` or

``wx.TRANSPARENT``.","

:see: `SetBackgroundMode`");

DocDeclStr(

const wxBrush& , GetBackground() const,

"Gets the brush used for painting the background.","

:see: `SetBackground`");

DocDeclStr(

const wxBrush& , GetBrush() const,

"Gets the current brush", "");

DocDeclStr(

const wxFont& , GetFont() const,

"Gets the current font", "");

DocDeclStr(

const wxPen& , GetPen() const,

"Gets the current pen", "");

DocDeclStr(

const wxColour , GetTextBackground() const,

"Gets the current text background colour", "");

DocDeclStr(

const wxColour , GetTextForeground() const,

"Gets the current text foreground colour", "");

DocDeclStr(

virtual void , SetTextForeground(const wxColour& colour),

"Sets the current text foreground colour for the DC.", "");

DocDeclStr(

virtual void , SetTextBackground(const wxColour& colour),

"Sets the current text background colour for the DC.", "");

DocDeclStr(

int , GetMapMode() const,

"Gets the current *mapping mode* for the device context ", "");

DocDeclStr(

virtual void , SetMapMode(wxMappingMode mode),

"The *mapping mode* of the device context defines the unit of

measurement used to convert logical units to device units. The

mapping mode can be one of the following:

================ =============================================

wx.MM_TWIPS Each logical unit is 1/20 of a point, or 1/1440

of an inch.

wx.MM_POINTS Each logical unit is a point, or 1/72 of an inch.

wx.MM_METRIC Each logical unit is 1 mm.

wx.MM_LOMETRIC Each logical unit is 1/10 of a mm.

wx.MM_TEXT Each logical unit is 1 pixel.

================ =============================================

","

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.

");

DocDeclAStr(

virtual void, GetUserScale(double *OUTPUT, double *OUTPUT) const,

"GetUserScale(self) -> (xScale, yScale)",

"Gets the current user scale factor (set by `SetUserScale`).", "");

DocDeclStr(

virtual void , SetUserScale(double x, double y),

"Sets the user scaling factor, useful for applications which require

'zooming'.", "");

DocDeclA(

virtual void, GetLogicalScale(double *OUTPUT, double *OUTPUT),

"GetLogicalScale() -> (xScale, yScale)");

virtual void SetLogicalScale(double x, double y);

wxPoint GetLogicalOrigin() const;

DocDeclAName(

void, GetLogicalOrigin(wxCoord *OUTPUT, wxCoord *OUTPUT) const,

"GetLogicalOriginTuple() -> (x,y)",

GetLogicalOriginTuple);

virtual void SetLogicalOrigin(wxCoord x, wxCoord y);

%extend {

void SetLogicalOriginPoint(const wxPoint& point) {

self->SetLogicalOrigin(point.x, point.y);

}

}

wxPoint GetDeviceOrigin() const;

DocDeclAName(

void, GetDeviceOrigin(wxCoord *OUTPUT, wxCoord *OUTPUT) const,

"GetDeviceOriginTuple() -> (x,y)",

GetDeviceOriginTuple);

virtual void SetDeviceOrigin(wxCoord x, wxCoord y);

%extend {

void SetDeviceOriginPoint(const wxPoint& point) {

self->SetDeviceOrigin(point.x, point.y);

}

}

DocDeclStr(

virtual 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). The default orientation is the natural

orientation, e.g. x axis from left to right and y axis from bottom up.", "");