X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..071de7a097edd90a8f39d4624b26b5744560e677:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 107cc06058..67542826ee 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -6,9 +6,83 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + +/** + Logical raster operations which can be used with wxDC::SetLogicalFunction + and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit). + + The description of the values below refer to how a generic @e src source pixel + and the corresponding @e dst destination pixel gets combined together to produce + the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source + and the destination pixel and always put zeroes or ones in the final surface. +*/ +enum wxRasterOperationMode +{ + wxCLEAR, //!< 0 + wxXOR, //!< @e src XOR @e dst + wxINVERT, //!< NOT @e dst + wxOR_REVERSE, //!< @e src OR (NOT @e dst) + wxAND_REVERSE, //!< @e src AND (NOT @e dst) + wxCOPY, //!< @e src + wxAND, //!< @e src AND @e dst + wxAND_INVERT, //!< (NOT @e src) AND @e dst + wxNO_OP, //!< @e dst + wxNOR, //!< (NOT @e src) AND (NOT @e dst) + wxEQUIV, //!< (NOT @e src) XOR @e dst + wxSRC_INVERT, //!< (NOT @e src) + wxOR_INVERT, //!< (NOT @e src) OR @e dst + wxNAND, //!< (NOT @e src) OR (NOT @e dst) + wxOR, //!< @e src OR @e dst + wxSET //!< 1 +}; + +/** + Flood styles used by wxDC::FloodFill. +*/ +enum wxFloodFillStyle +{ + /** The flooding occurs until a colour other than the given colour is encountered. */ + wxFLOOD_SURFACE = 1, + + /** The area to be flooded is bounded by the given colour. */ + wxFLOOD_BORDER +}; + +/** + The mapping used to transform @e logical units to @e device units. + See wxDC::SetMapMode. +*/ +enum wxMappingMode +{ + /** + Each logical unit is 1 device pixel. + This is the default mapping mode for all wxDC-derived classes. + */ + wxMM_TEXT = 1, + + /** Each logical unit is 1 millimeter. */ + wxMM_METRIC, + + /** Each logical unit is 1/10 of a millimeter. */ + wxMM_LOMETRIC, + + /** + Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch + (also known as "twip"). Equivalent to about 17.64 micrometers. + */ + wxMM_TWIPS, + + /** + Each logical unit is a @e "printer point" i.e. 1/72 of an inch. + Equivalent to about 353 micrometers. + */ + wxMM_POINTS +}; + + + /** @class wxDC - @wxheader{dc.h} A wxDC is a @e "device context" onto which graphics and text can be drawn. It is intended to represent different output devices and offers a common @@ -38,151 +112,113 @@ wxDCImpl class. The user-visible classes such as wxClientDC and wxPaintDC merely forward all calls to the backend implementation. - On Mac OS X colours with alpha channel are supported. Instances wxPen + + @section dc_units Device and logical units + + In the wxDC context there is a distinction between @e logical units and @e device units. + + @b Device units are the units native to the particular device; e.g. for a screen, + a device unit is a @e pixel. For a printer, the device unit is defined by the + resolution of the printer (usually given in @c DPI: dot-per-inch). + + All wxDC functions use instead @b logical units, unless where explicitely + stated. Logical units are arbitrary units mapped to device units using + the current mapping mode (see wxDC::SetMapMode). + + This mechanism allows to reuse the same code which prints on e.g. a window + on the screen to print on e.g. a paper. + + + @section dc_alpha_support Support for Transparency / Alpha Channel + + On Mac OS X colours with alpha channel are supported. Instances of wxPen or wxBrush that are built from wxColour use the colour's alpha values when stroking or filling. + @library{wxcore} @category{dc,gdi} - @see @ref overview_dc, wxGraphicsContext + @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger, + wxDCPenChanger, wxDCBrushChanger, wxDCClipper @todo Precise definition of default/initial state. @todo Pixelwise definition of operations (e.g. last point of a line not drawn). - @todo Coordinates: state clearly which type of coordinates are returned by - the various Get*Point() or similar functions - often they are client - coordinates but not always. */ class wxDC : public wxObject { public: /** - Copy from a source DC to this DC, specifying the destination - coordinates, size of area to copy, source DC, source coordinates, - logical function, whether to use a bitmap mask, and mask source - position. - - @param xdest - Destination device context x position. - @param ydest - Destination device context y position. - @param width - Width of source area to be copied. - @param height - Height of source area to be copied. - @param source - Source device context. - @param xsrc - Source device context x position. - @param ysrc - Source device context y position. - @param logicalFunc - Logical function to use, see SetLogicalFunction(). - @param useMask - If @true, Blit does a transparent blit using the mask that is - associated with the bitmap selected into the source device context. - The Windows implementation does the following if MaskBlt cannot be - used: -
    -
  1. Creates a temporary bitmap and copies the destination area into - it.
    2. -
  2. Copies the source area into the temporary bitmap using the - specified logical function.
    3. -
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing - the mask bitmap with the temp bitmap with the foreground colour - set to WHITE and the bg colour set to BLACK.
    4. -
  4. Sets the unmasked area in the destination area to BLACK by - ANDing the mask bitmap with the destination area with the - foreground colour set to BLACK and the background colour set to - WHITE.
    5. -
  5. ORs the temporary bitmap with the destination area.
    6. -
  6. Deletes the temporary bitmap.
    7. -
- This sequence of operations ensures that the source's transparent - area need not be black, and logical functions are supported. - @n @b Note: on Windows, blitting with masks can be speeded up - considerably by compiling wxWidgets with the wxUSE_DC_CACHE option - enabled. You can also influence whether MaskBlt or the explicit - mask blitting code above is used, by using wxSystemOptions and - setting the @c no-maskblt option to 1. - @param xsrcMask - Source x position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - @param ysrcMask - Source y position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. - - @remarks There is partial support for Blit() in wxPostScriptDC, under X. - - @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask + @name Coordinate conversion functions */ - bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, - wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, - int logicalFunc = wxCOPY, bool useMask = false, - wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); + //@{ /** - Adds the specified point to the bounding box which can be retrieved - with MinX(), MaxX() and MinY(), MaxY() functions. - - @see ResetBoundingBox() + Convert @e device X coordinate to logical coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. */ - void CalcBoundingBox(wxCoord x, wxCoord y); + wxCoord DeviceToLogicalX(wxCoord x) const; /** - Clears the device context using the current background brush. + Convert @e device X coordinate to relative logical coordinate, using the + current mapping mode and user scale factor but ignoring the + axis orientation. Use this for converting a width, for example. */ - void Clear(); + wxCoord DeviceToLogicalXRel(wxCoord x) const; /** - Performs all necessary computations for given platform and context type - after each change of scale and origin parameters. Usually called - automatically internally after such changes. + Converts @e device Y coordinate to logical coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. */ - virtual void ComputeScaleAndOrigin(); + wxCoord DeviceToLogicalY(wxCoord y) const; /** - Displays a cross hair using the current pen. This is a vertical and - horizontal line the height and width of the window, centred on the - given point. + Convert @e device Y coordinate to relative logical coordinate, using the + current mapping mode and user scale factor but ignoring the + axis orientation. Use this for converting a height, for example. */ - void CrossHair(wxCoord x, wxCoord y); + wxCoord DeviceToLogicalYRel(wxCoord y) const; /** - Destroys the current clipping region so that none of the DC is clipped. + Converts logical X coordinate to device coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. + */ + wxCoord LogicalToDeviceX(wxCoord x) const; - @see SetClippingRegion() + /** + Converts logical X coordinate to relative device coordinate, using the + current mapping mode and user scale factor but ignoring the + axis orientation. Use this for converting a width, for example. */ - void DestroyClippingRegion(); + wxCoord LogicalToDeviceXRel(wxCoord x) const; /** - Convert device X coordinate to logical coordinate, using the current - mapping mode. + Converts logical Y coordinate to device coordinate, using the current + mapping mode, user scale factor, device origin and axis orientation. */ - virtual wxCoord DeviceToLogicalX(wxCoord x); + wxCoord LogicalToDeviceY(wxCoord y) 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. + Converts logical Y coordinate to relative device coordinate, using the + current mapping mode and user scale factor but ignoring the + axis orientation. Use this for converting a height, for example. */ - virtual wxCoord DeviceToLogicalXRel(wxCoord x); + wxCoord LogicalToDeviceYRel(wxCoord y) const; + + //@} + + /** - Converts device Y coordinate to logical coordinate, using the current - mapping mode. + @name Drawing functions */ - virtual wxCoord DeviceToLogicalY(wxCoord y); + //@{ /** - 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. + Clears the device context using the current background brush. */ - virtual wxCoord DeviceToLogicalYRel(wxCoord y); + void Clear(); /** Draws an arc of a circle, centred on (@a xc, @a yc), with starting @@ -193,7 +229,7 @@ public: to the end point. */ void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, - wxCoord xc, wxCoord yc); + wxCoord xc, wxCoord yc); /** Draw a bitmap on the device context at the specified point. If @@ -208,27 +244,30 @@ public: @see SetTextForeground(), SetTextBackground(), wxMemoryDC */ void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, - bool transparent); + bool useMask = false); - //@{ /** Draws a check mark inside the given rectangle. */ void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + @overload + */ void DrawCheckMark(const wxRect& rect); - //@} - //@{ /** Draws a circle with the given centre and radius. @see DrawEllipse() */ void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); + + /** + @overload + */ void DrawCircle(const wxPoint& pt, wxCoord radius); - //@} - //@{ /** Draws an ellipse contained in the rectangle specified either with the given top left corner and the given size or directly. The current pen @@ -237,9 +276,16 @@ public: @see DrawCircle() */ void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + + /** + @overload + */ void DrawEllipse(const wxPoint& pt, const wxSize& size); + + /** + @overload + */ void DrawEllipse(const wxRect& rect); - //@} /** Draws an arc of an ellipse. The current pen is used for drawing the arc @@ -267,21 +313,23 @@ public: */ void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); - //@{ /** Draw optional bitmap and the text into the given rectangle and aligns it as specified by alignment parameter; it also will emphasize the character with the given index if it is != -1 and return the bounding rectangle if required. */ - virtual void DrawLabel(const wxString& text, const wxBitmap& image, - const wxRect& rect, - int alignment = wxALIGN_LEFT | wxALIGN_TOP, - int indexAccel = -1, wxRect* rectBounding = NULL); + void DrawLabel(const wxString& text, const wxBitmap& image, + const wxRect& rect, + int alignment = wxALIGN_LEFT | wxALIGN_TOP, + int indexAccel = -1, wxRect* rectBounding = NULL); + + /** + @overload + */ void DrawLabel(const wxString& text, const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1); - //@} /** Draws a line from the first point to the second. The current pen is @@ -333,7 +381,8 @@ public: for filling the shape. Using a transparent brush suppresses filling. */ void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, - wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE); + wxCoord yoffset = 0, + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** This method draws a filled polygon using a list of wxPoints, adding the optional offset coordinate. The first and last points are automatically @@ -354,7 +403,7 @@ public: */ void DrawPolygon(const wxPointList* points, wxCoord xoffset = 0, wxCoord yoffset = 0, - int fill_style = wxODDEVEN_RULE); + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** Draws two or more filled polygons using an array of @a points, adding @@ -385,7 +434,7 @@ public: */ void DrawPolyPolygon(int n, int count[], wxPoint points[], wxCoord xoffset = 0, wxCoord yoffset = 0, - int fill_style = wxODDEVEN_RULE); + wxPolygonFillMode fill_style = wxODDEVEN_RULE); /** Draws a rectangle with the given top left corner, and with the given @@ -395,7 +444,8 @@ public: void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); /** - Draws the text rotated by @a angle degrees. + Draws the text rotated by @a angle degrees + (positive angles are counterclockwise; the full angle is 360 degrees). @note Under Win9x only TrueType fonts can be drawn by this function. In particular, a font different from @c wxNORMAL_FONT should be used @@ -423,7 +473,6 @@ public: void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius); - //@{ /** Draws a spline between all given points using the current pen. @@ -433,10 +482,17 @@ public: @endWxPythonOnly */ void DrawSpline(int n, wxPoint points[]); + + /** + @overload + */ void DrawSpline(const wxPointList* points); + + /** + @overload + */ void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord x3, wxCoord y3); - //@} /** Draws a text string at the specified point, using the current text @@ -446,22 +502,52 @@ public: 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 - @ref GetLogicalFunction() "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. + @note The current @ref GetLogicalFunction() "logical function" is + ignored by this function. */ void DrawText(const wxString& text, wxCoord x, wxCoord y); /** - Ends a document (only relevant when outputting to a printer). + Fill the area specified by rect with a radial gradient, starting from + @a initialColour at the centre of the circle and fading to + @a destColour on the circle outside. + + The circle is placed at the centre of @a rect. + + @note Currently this function is very slow, don't use it for real-time + drawing. */ - void EndDoc(); + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour); /** - Ends a document page (only relevant when outputting to a printer). + Fill the area specified by rect with a radial gradient, starting from + @a initialColour at the centre of the circle and fading to + @a destColour on the circle outside. + + @a circleCenter are the relative coordinates of centre of the circle in + the specified @a rect. + + @note Currently this function is very slow, don't use it for real-time + drawing. */ - void EndPage(); + void GradientFillConcentric(const wxRect& rect, + const wxColour& initialColour, + const wxColour& destColour, + const wxPoint& circleCenter); + + /** + Fill the area specified by @a rect with a linear gradient, starting + from @a initialColour and eventually fading to @e destColour. + + The @a nDirection specifies the direction of the colour change, default is + to use @a initialColour on the left part of the rectangle and + @a destColour on the right one. + */ + void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, + const wxColour& destColour, + wxDirection nDirection = wxRIGHT); /** Flood fills the device context starting from the given point, using @@ -479,38 +565,29 @@ public: exactly. However the function will still return @true. */ bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, - int style = wxFLOOD_SURFACE); + wxFloodFillStyle style = wxFLOOD_SURFACE); /** - Gets the brush used for painting the background. - - @see wxDC::SetBackground() + 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. */ - const wxBrush GetBackground() const; + void CrossHair(wxCoord x, wxCoord y); - /** - Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. + //@} - @see SetBackgroundMode() - */ - int GetBackgroundMode() const; /** - Gets the current brush. - - @see wxDC::SetBrush() + @name Clipping region functions */ - const wxBrush GetBrush() const; + //@{ /** - Gets the character height of the currently set font. - */ - wxCoord GetCharHeight(); + Destroys the current clipping region so that none of the DC is clipped. - /** - Gets the average character width of the currently set font. + @see SetClippingRegion() */ - wxCoord GetCharWidth(); + void DestroyClippingRegion(); /** Gets the rectangle surrounding the current clipping region. @@ -520,49 +597,60 @@ public: are returned as a tuple. @endWxPythonOnly */ - void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height); + void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; /** - Returns the depth (number of bits/pixel) of this DC. + Sets the clipping region for this device context to the intersection of + the given region described by the parameters of this method and the + previously set clipping region. You should call DestroyClippingRegion() + if you want to set the clipping region exactly to the region specified. - @see wxDisplayDepth() + The clipping region is an area to which drawing is restricted. Possible + uses for the clipping region are for clipping text or for speeding up + window redraws when only a known area of the screen is damaged. + + @see DestroyClippingRegion(), wxRegion */ - int GetDepth() const; + void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); /** - Gets the current font. Notice that even although each device context - object has some default font after creation, this method would return a - wxNullFont initially and only after calling SetFont() a valid font is - returned. + @overload */ - const wxFont GetFont() const; + void SetClippingRegion(const wxPoint& pt, const wxSize& sz); /** - Gets the current layout direction of the device context. On platforms - where RTL layout is supported, the return value will either be - @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is - not supported, the return value will be @c wxLayout_Default. - - @see SetLayoutDirection() + @overload */ - wxLayoutDirection GetLayoutDirection() const; + void SetClippingRegion(const wxRect& rect); /** - Gets the current logical function. + Sets the clipping region for this device context. - @see SetLogicalFunction() - */ - int GetLogicalFunction(); + Unlike SetClippingRegion(), this function works with physical + coordinates and not with the logical ones. + */ + void SetDeviceClippingRegion(const wxRegion& region); - /** - Gets the mapping mode for the device context. + //@} - @see SetMapMode() + + /** + @name Text/character extent functions */ - int GetMapMode(); + //@{ /** - Gets the dimensions of the string using the currently selected font. + Gets the character height of the currently set font. + */ + wxCoord GetCharHeight() const; + + /** + Gets the average character width of the currently set font. + */ + wxCoord GetCharWidth() const; + + /** + Gets the dimensions of the string using the currently selected font. @a string is the text string to measure, @e heightLine, if non @NULL, is where to store the height of a single line. @@ -579,7 +667,7 @@ public: void GetMultiLineTextExtent(const wxString& string, wxCoord* w, wxCoord* h, wxCoord* heightLine = NULL, - wxFont* font = NULL) const; + const wxFont* font = NULL) const; /** Gets the dimensions of the string using the currently selected font. @a string is the text string to measure, @e heightLine, if non @NULL, @@ -591,7 +679,7 @@ public: @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() */ - const wxSize GetMultiLineTextExtent(const wxString& string) const; + wxSize GetMultiLineTextExtent(const wxString& string) const; /** Fills the @a widths array with the widths from the beginning of @a text @@ -611,74 +699,6 @@ public: bool GetPartialTextExtents(const wxString& text, wxArrayInt& widths) const; - /** - Gets the current pen. - - @see SetPen() - */ - const wxPen GetPen() const; - - /** - Gets in @a colour the colour at the specified location. Not available - for wxPostScriptDC or wxMetafileDC. - - @note Setting a pixel can be done using DrawPoint(). - - @beginWxPythonOnly - The wxColour value is returned and is not required as a parameter. - @endWxPythonOnly - */ - bool GetPixel(wxCoord x, wxCoord y, wxColour* colour); - - /** - Returns the resolution of the device in pixels per inch. - */ - wxSize GetPPI() const; - - //@{ - /** - This gets the horizontal and vertical resolution in device units. It - can be used to scale graphics to fit the page. - - For example, if @e maxX and @e maxY represent the maximum horizontal - and vertical 'pixel' values used in your application, the following - code will scale the graphic to fit on the printer page: - - @code - wxCoord w, h; - dc.GetSize(&w, &h); - double scaleX = (double)(maxX / w); - double scaleY = (double)(maxY / h); - dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); - @endcode - - @beginWxPythonOnly - In place of a single overloaded method name, wxPython implements the - following methods: - - GetSize() - Returns a wxSize. - - GetSizeWH() - Returns a 2-tuple (width, height). - @endWxPythonOnly - */ - void GetSize(wxCoord* width, wxCoord* height) const; - const wxSize GetSize() const; - //@} - - //@{ - /** - Returns the horizontal and vertical resolution in millimetres. - */ - void GetSizeMM(wxCoord* width, wxCoord* height) const; - const wxSize GetSizeMM() const; - //@} - - /** - Gets the current text background colour. - - @see SetTextBackground() - */ - const wxColour GetTextBackground() const; - - //@{ /** Gets the dimensions of the string using the currently selected font. @a string is the text string to measure, @a descent is the dimension @@ -709,312 +729,242 @@ public: wxCoord* descent = NULL, wxCoord* externalLeading = NULL, const wxFont* font = NULL) const; - const wxSize GetTextExtent(const wxString& string) const; - //@} /** - Gets the current text foreground colour. - - @see SetTextForeground() + @overload */ - const wxColour GetTextForeground() const; + wxSize GetTextExtent(const wxString& string) const; - /** - Gets the current user scale factor. + //@} - @see SetUserScale() - */ - void GetUserScale(double x, double y); - //@{ /** - Fill the area specified by rect with a radial gradient, starting from - @a initialColour at the centre of the circle and fading to - @a destColour on the circle outside. + @name Text properties functions + */ + //@{ - @a circleCenter are the relative coordinates of centre of the circle in - the specified @e rect. If not specified, the circle is placed at the - centre of rect. + /** + Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. - @note Currently this function is very slow, don't use it for real-time - drawing. + @see SetBackgroundMode() */ - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour); - void GradientFillConcentric(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour, - const wxPoint& circleCenter); - //@} + int GetBackgroundMode() const; /** - Fill the area specified by @a rect with a linear gradient, starting - from @a initialColour and eventually fading to @e destColour. The - @a nDirection specifies the direction of the colour change, default is - to use @a initialColour on the left part of the rectangle and - @a destColour on the right one. + Gets the current font. Notice that even although each device context + object has some default font after creation, this method would return a + ::wxNullFont initially and only after calling SetFont() a valid font is + returned. */ - void GradientFillLinear(const wxRect& rect, - const wxColour& initialColour, - const wxColour& destColour, - wxDirection nDirection = wxEAST); + const wxFont& GetFont() const; /** - Returns @true if the DC is ok to use. + Gets the current layout direction of the device context. On platforms + where RTL layout is supported, the return value will either be + @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is + not supported, the return value will be @c wxLayout_Default. + + @see SetLayoutDirection() */ - bool Ok(); + wxLayoutDirection GetLayoutDirection() const; /** - Converts logical X coordinate to device coordinate, using the current - mapping mode. + Gets the current text background colour. + + @see SetTextBackground() */ - virtual wxCoord LogicalToDeviceX(wxCoord x); + const wxColour& GetTextBackground() 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. + Gets the current text foreground colour. + + @see SetTextForeground() */ - virtual wxCoord LogicalToDeviceXRel(wxCoord x); + const wxColour& GetTextForeground() const; /** - Converts logical Y coordinate to device coordinate, using the current - mapping mode. + @a mode may be one of wxSOLID and wxTRANSPARENT. This setting + determines whether text will be drawn with a background colour or not. */ - virtual wxCoord LogicalToDeviceY(wxCoord y); + void SetBackgroundMode(int mode); /** - 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. + Sets the current font for the DC. It must be a valid font, in + particular you should not pass wxNullFont to this method. + + @see wxFont */ - virtual wxCoord LogicalToDeviceYRel(wxCoord y); + void SetFont(const wxFont& font); /** - Gets the maximum horizontal extent used in drawing commands so far. + Sets the current text background colour for the DC. */ - wxCoord MaxX(); + void SetTextBackground(const wxColour& colour); /** - Gets the maximum vertical extent used in drawing commands so far. + Sets the current text foreground colour for the DC. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. */ - wxCoord MaxY(); + void SetTextForeground(const wxColour& colour); /** - Gets the minimum horizontal extent used in drawing commands so far. + Sets the current layout direction for the device context. @a dir may be + either @c wxLayout_Default, @c wxLayout_LeftToRight or + @c wxLayout_RightToLeft. + + @see GetLayoutDirection() */ - wxCoord MinX(); + void SetLayoutDirection(wxLayoutDirection dir); + + //@} + /** - Gets the minimum vertical extent used in drawing commands so far. + @name Bounding box functions */ - wxCoord MinY(); + //@{ /** - Resets the bounding box: after a call to this function, the bounding - box doesn't contain anything. + Adds the specified point to the bounding box which can be retrieved + with MinX(), MaxX() and MinY(), MaxY() functions. - @see CalcBoundingBox() + @see ResetBoundingBox() */ - void ResetBoundingBox(); + void CalcBoundingBox(wxCoord x, wxCoord y); /** - Sets the x and y axis orientation (i.e., the direction from lowest to - highest values on the axis). The default orientation is x axis from - left to right and y axis from top down. - - @param xLeftRight - True to set the x axis orientation to the natural left to right - orientation, @false to invert it. - @param yBottomUp - True to set the y axis orientation to the natural bottom up - orientation, @false to invert it. + Gets the maximum horizontal extent used in drawing commands so far. */ - void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + wxCoord MaxX() const; /** - Sets the current background brush for the DC. + Gets the maximum vertical extent used in drawing commands so far. */ - void SetBackground(const wxBrush& brush); + wxCoord MaxY() const; /** - @a mode may be one of wxSOLID and wxTRANSPARENT. This setting - determines whether text will be drawn with a background colour or not. + Gets the minimum horizontal extent used in drawing commands so far. */ - void SetBackgroundMode(int mode); + wxCoord MinX() const; /** - Sets the current brush for the DC. - - If the argument is wxNullBrush, the current brush is selected out of - the device context (leaving wxDC without any valid brush), allowing the - current brush to be destroyed safely. - - @see wxBrush, wxMemoryDC (for the interpretation of colours when - drawing into a monochrome bitmap) + Gets the minimum vertical extent used in drawing commands so far. */ - void SetBrush(const wxBrush& brush); + wxCoord MinY() const; - //@{ /** - 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. + Resets the bounding box: after a call to this function, the bounding + box doesn't contain anything. - @see DestroyClippingRegion(), wxRegion + @see CalcBoundingBox() */ - void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, - wxCoord height); - void SetClippingRegion(const wxPoint& pt, const wxSize& sz); - void SetClippingRegion(const wxRect& rect); - //@} + void ResetBoundingBox(); - /** - Sets the clipping region for this device context. + //@} - Unlike SetClippingRegion(), this function works with physical - coordinates and not with the logical ones. - */ - void SetDeviceClippingRegion(const wxRegion& region); /** - Sets the device origin (i.e., the origin in pixels after scaling has - been applied). This function may be useful in Windows printing - operations for placing a graphic on a page. + @name Page and document start/end functions */ - void SetDeviceOrigin(wxCoord x, wxCoord y); + //@{ /** - Sets the current font for the DC. It must be a valid font, in - particular you should not pass wxNullFont to this method. - - @see wxFont + Starts a document (only relevant when outputting to a printer). + @a message is a message to show while printing. */ - void SetFont(const wxFont& font); + bool StartDoc(const wxString& message); /** - Sets the current layout direction for the device context. @a dir may be - either @c wxLayout_Default, @c wxLayout_LeftToRight or - @c wxLayout_RightToLeft. - - @see GetLayoutDirection() + Starts a document page (only relevant when outputting to a printer). */ - void SetLayoutDirection(wxLayoutDirection dir); + void StartPage(); /** - Sets the current logical function for the device context. This - determines how a source pixel (from a pen or brush colour, or source - device context if using Blit()) combines with a destination pixel in - the current device context. - - The possible values and their meaning in terms of source and - destination pixel values are as follows: - - @verbatim - wxAND src AND dst - wxAND_INVERT (NOT src) AND dst - wxAND_REVERSE src AND (NOT dst) - wxCLEAR 0 - wxCOPY src - wxEQUIV (NOT src) XOR dst - wxINVERT NOT dst - wxNAND (NOT src) OR (NOT dst) - wxNOR (NOT src) AND (NOT dst) - wxNO_OP dst - wxOR src OR dst - wxOR_INVERT (NOT src) OR dst - wxOR_REVERSE src OR (NOT dst) - wxSET 1 - wxSRC_INVERT NOT src - wxXOR src XOR dst - @endverbatim - - The default is wxCOPY, which simply draws with the current colour. The - others combine the current colour and the background using a logical - operation. wxINVERT is commonly used for drawing rubber bands or moving - outlines, since drawing twice reverts to the original colour. + Ends a document (only relevant when outputting to a printer). */ - void SetLogicalFunction(int function); + void EndDoc(); /** - The mapping mode of the device context defines the unit of measurement - used to convert logical units to device units. Note that in X, text - drawing isn't handled consistently with the mapping mode; a font is - always specified in point size. However, setting the user scale (see - SetUserScale()) scales the text appropriately. In Windows, scalable - TrueType fonts are always used; in X, results depend on availability of - fonts, but usually a reasonable match is found. + Ends a document page (only relevant when outputting to a printer). + */ + void EndPage(); - 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. - The mapping mode can be one of the following: - - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an - inch. - - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch. - - wxMM_METRIC: Each logical unit is 1 mm. - - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm. - - wxMM_TEXT: Each logical unit is 1 device pixel. + /** + @name Bit-Block Transfer operations (blit) */ - void SetMapMode(int mode); + //@{ /** - If this is a window DC or memory DC, assigns the given palette to the - window or bitmap associated with the DC. If the argument is - wxNullPalette, the current palette is selected out of the device - context, and the original palette restored. - - @see wxPalette - */ - void SetPalette(const wxPalette& palette); - - /** - Sets the current pen for the DC. If the argument is wxNullPen, the - current pen is selected out of the device context (leaving wxDC without - any valid pen), allowing the current brush to be destroyed safely. - - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. - */ - void SetPen(const wxPen& pen); - - /** - Sets the current text background colour for the DC. - */ - void SetTextBackground(const wxColour& colour); - - /** - Sets the current text foreground colour for the DC. - - @see wxMemoryDC for the interpretation of colours when drawing into a - monochrome bitmap. - */ - void SetTextForeground(const wxColour& colour); + 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. - /** - Sets the user scaling factor, useful for applications which require - 'zooming'. - */ - void SetUserScale(double xScale, double yScale); + @param xdest + Destination device context x position. + @param ydest + Destination device context y position. + @param width + Width of source area to be copied. + @param height + Height of source area to be copied. + @param source + Source device context. + @param xsrc + Source device context x position. + @param ysrc + Source device context y position. + @param logicalFunc + Logical function to use, see SetLogicalFunction(). + @param useMask + If @true, Blit does a transparent blit using the mask that is + associated with the bitmap selected into the source device context. + The Windows implementation does the following if MaskBlt cannot be + used: +
    +
  1. Creates a temporary bitmap and copies the destination area into + it.
    2. +
  2. Copies the source area into the temporary bitmap using the + specified logical function.
    3. +
  3. Sets the masked area in the temporary bitmap to BLACK by ANDing + the mask bitmap with the temp bitmap with the foreground colour + set to WHITE and the bg colour set to BLACK.
    4. +
  4. Sets the unmasked area in the destination area to BLACK by + ANDing the mask bitmap with the destination area with the + foreground colour set to BLACK and the background colour set to + WHITE.
    5. +
  5. ORs the temporary bitmap with the destination area.
    6. +
  6. Deletes the temporary bitmap.
    7. +
+ This sequence of operations ensures that the source's transparent + area need not be black, and logical functions are supported. + @n @b Note: on Windows, blitting with masks can be speeded up + considerably by compiling wxWidgets with the wxUSE_DC_CACHE option + enabled. You can also influence whether MaskBlt or the explicit + mask blitting code above is used, by using wxSystemOptions and + setting the @c no-maskblt option to 1. + @param xsrcMask + Source x position on the mask. If both xsrcMask and ysrcMask are + @c -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. + @param ysrcMask + Source y position on the mask. If both xsrcMask and ysrcMask are + @c -1, xsrc and ysrc will be assumed for the mask source position. + Currently only implemented on Windows. - /** - Starts a document (only relevant when outputting to a printer). - @a message is a message to show while printing. - */ - bool StartDoc(const wxString& message); + @remarks There is partial support for Blit() in wxPostScriptDC, under X. - /** - Starts a document page (only relevant when outputting to a printer). + @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask */ - bool StartPage(); + 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, specifying the destination @@ -1071,12 +1021,12 @@ public: setting the @c no-maskblt option to 1. @param xsrcMask Source x position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. + wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask + source position. Currently only implemented on Windows. @param ysrcMask Source y position on the mask. If both xsrcMask and ysrcMask are - -1, xsrc and ysrc will be assumed for the mask source position. - Currently only implemented on Windows. + wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask + source position. Currently only implemented on Windows. There is partial support for Blit() in wxPostScriptDC, under X. @@ -1092,16 +1042,242 @@ public: wxCoord dstWidth, wxCoord dstHeight, wxDC* source, wxCoord xsrc, wxCoord ysrc, wxCoord srcWidth, wxCoord srcHeight, - int logicalFunc = wxCOPY, + wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, - wxCoord xsrcMask = -1, wxCoord ysrcMask = -1); + wxCoord xsrcMask = wxDefaultCoord, + wxCoord ysrcMask = wxDefaultCoord); + //@} + + + /** + @name Background/foreground brush and pen + */ + //@{ + + /** + Gets the brush used for painting the background. + + @see wxDC::SetBackground() + */ + const wxBrush& GetBackground() const; + + /** + Gets the current brush. + + @see wxDC::SetBrush() + */ + const wxBrush& GetBrush() const; + + /** + Gets the current pen. + + @see SetPen() + */ + const wxPen& GetPen() const; + + /** + Sets the current background brush for the DC. + */ + void SetBackground(const wxBrush& brush); + + /** + Sets the current brush for the DC. + + If the argument is wxNullBrush, the current brush is selected out of + the device context (leaving wxDC without any valid brush), allowing the + current brush to be destroyed safely. + + @see wxBrush, wxMemoryDC (for the interpretation of colours when + drawing into a monochrome bitmap) + */ + void SetBrush(const wxBrush& brush); + + /** + Sets the current pen for the DC. If the argument is wxNullPen, the + current pen is selected out of the device context (leaving wxDC without + any valid pen), allowing the current brush to be destroyed safely. + + @see wxMemoryDC for the interpretation of colours when drawing into a + monochrome bitmap. + */ + void SetPen(const wxPen& pen); + + //@} + + + + /** + Returns the depth (number of bits/pixel) of this DC. + + @see wxDisplayDepth() + */ + int GetDepth() const; + + /** + Returns the current device origin. + + @see SetDeviceOrigin() + */ + wxPoint GetDeviceOrigin() const; + + /** + Gets the current logical function. + + @see SetLogicalFunction() + */ + wxRasterOperationMode GetLogicalFunction() const; + + /** + Gets the current mapping mode for the device context. + + @see SetMapMode() + */ + wxMappingMode GetMapMode() const; + + /** + Gets in @a colour the colour at the specified location. Not available + for wxPostScriptDC or wxMetafileDC. + + @note Setting a pixel can be done using DrawPoint(). + + @beginWxPythonOnly + The wxColour value is returned and is not required as a parameter. + @endWxPythonOnly + */ + bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; + + /** + Returns the resolution of the device in pixels per inch. + */ + wxSize GetPPI() const; + + /** + Gets the horizontal and vertical extent of this device context in @e device units. + It can be used to scale graphics to fit the page. + + For example, if @e maxX and @e maxY represent the maximum horizontal + and vertical 'pixel' values used in your application, the following + code will scale the graphic to fit on the printer page: + + @code + wxCoord w, h; + dc.GetSize(&w, &h); + double scaleX = (double)(maxX / w); + double scaleY = (double)(maxY / h); + dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); + @endcode + + @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 + */ + void GetSize(wxCoord* width, wxCoord* height) const; + + /** + @overload + */ + wxSize GetSize() const; + + /** + Returns the horizontal and vertical resolution in millimetres. + */ + void GetSizeMM(wxCoord* width, wxCoord* height) const; + + /** + @overload + */ + wxSize GetSizeMM() const; + + /** + Gets the current user scale factor. + + @see SetUserScale() + */ + void GetUserScale(double* x, double* y) const; + + /** + Returns @true if the DC is ok to use. + */ + bool IsOk() const; + + /** + Sets the x and y axis orientation (i.e., the direction from lowest to + highest values on the axis). The default orientation is x axis from + left to right and y axis from top down. + + @param xLeftRight + True to set the x axis orientation to the natural left to right + orientation, @false to invert it. + @param yBottomUp + True to set the y axis orientation to the natural bottom up + orientation, @false to invert it. + */ + void SetAxisOrientation(bool xLeftRight, bool yBottomUp); + + /** + Sets the device origin (i.e., the origin in pixels after scaling has + been applied). This function may be useful in Windows printing + operations for placing a graphic on a page. + */ + void SetDeviceOrigin(wxCoord x, wxCoord y); + + /** + Sets the current logical function for the device context. + It determines how a @e source pixel (from a pen or brush colour, or source + device context if using Blit()) combines with a @e destination pixel in + the current device context. + Text drawing is not affected by this function. + + See ::wxRasterOperationMode enumeration values for more info. + + The default is @c wxCOPY, which simply draws with the current colour. + The others combine the current colour and the background using a logical + operation. @c wxINVERT is commonly used for drawing rubber bands or moving + outlines, since drawing twice reverts to the original colour. + */ + void SetLogicalFunction(wxRasterOperationMode function); + + /** + The mapping mode of the device context defines the unit of measurement + used to convert @e logical units to @e device units. + + Note that in X, text drawing isn't handled consistently with the mapping mode; + a font is always specified in point size. However, setting the user scale (see + SetUserScale()) scales the text appropriately. In Windows, scalable + TrueType fonts are always used; in X, results depend on availability of + fonts, but usually a reasonable match is found. + + The coordinate origin is always at the top left of the screen/printer. + + Drawing to a Windows printer device context uses the current mapping + mode, but mapping mode is currently ignored for PostScript output. + */ + void SetMapMode(wxMappingMode mode); + + /** + If this is a window DC or memory DC, assigns the given palette to the + window or bitmap associated with the DC. If the argument is + ::wxNullPalette, the current palette is selected out of the device + context, and the original palette restored. + + @see wxPalette + */ + void SetPalette(const wxPalette& palette); + + /** + Sets the user scaling factor, useful for applications which require + 'zooming'. + */ + void SetUserScale(double xScale, double yScale); }; /** @class wxDCClipper - @wxheader{dc.h} 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 @@ -1126,7 +1302,8 @@ public: @library{wxcore} @category{gdi} - @see wxDC::SetClippingRegion() + @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, + wxDCBrushChanger */ class wxDCClipper { @@ -1139,7 +1316,145 @@ public: */ wxDCClipper(wxDC& dc, const wxRegion& r); wxDCClipper(wxDC& dc, const wxRect& rect); - wxDCClipper(wxDC& dc, int x, int y, int w, int h); + wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); //@} + + /** + Destroys the clipping region associated with the DC passed to the ctor. + */ + ~wxDCClipper(); +}; + + +/** + @class wxDCBrushChanger + + wxDCBrushChanger is a small helper class for setting a brush on a wxDC + and unsetting it automatically in the destructor, restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, + wxDCClipper +*/ +class wxDCBrushChanger +{ +public: + /** + Sets @a brush on the given @a dc, storing the old one. + + @param dc + The DC where the brush must be temporary set. + @param brush + The brush to set. + */ + wxDCBrushChanger(wxDC& dc, const wxBrush& brush); + + /** + Restores the brush originally selected in the DC passed to the ctor. + */ + ~wxDCBrushChanger(); +}; + + +/** + @class wxDCPenChanger + + wxDCPenChanger is a small helper class for setting a pen on a wxDC + and unsetting it automatically in the destructor, restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger, + wxDCClipper +*/ +class wxDCPenChanger +{ +public: + /** + Sets @a pen on the given @a dc, storing the old one. + + @param dc + The DC where the pen must be temporary set. + @param pen + The pen to set. + */ + wxDCPenChanger(wxDC& dc, const wxPen& pen); + + /** + Restores the pen originally selected in the DC passed to the ctor. + */ + ~wxDCPenChanger(); +}; + + + +/** + @class wxDCTextColourChanger + + wxDCTextColourChanger is a small helper class for setting a foreground + text colour on a wxDC and unsetting it automatically in the destructor, + restoring the previous one. + + @library{wxcore} + @category{gdi} + + @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, + wxDCClipper +*/ +class wxDCTextColourChanger +{ +public: + /** + Sets @a col on the given @a dc, storing the old one. + + @param dc + The DC where the colour must be temporary set. + @param col + The colour to set. + */ + wxDCTextColourChanger(wxDC& dc, const wxColour& col); + + /** + Restores the colour originally selected in the DC passed to the ctor. + */ + ~wxDCTextColourChanger(); +}; + + + +/** + @class wxDCFontChanger + + wxDCFontChanger is a small helper class for setting a font on a wxDC and + unsetting it automatically in the destructor, restoring the previous one. + + @since 2.9.0 + + @library{wxcore} + @category{gdi} + + @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger, + wxDCClipper +*/ +class wxDCFontChanger +{ +public: + /** + Sets @a font on the given @a dc, storing the old one. + + @param dc + The DC where the font must be temporary set. + @param font + The font to set. + */ + wxDCFontChanger(wxDC& dc, const wxFont& font); + + /** + Restores the colour originally selected in the DC passed to the ctor. + */ + ~wxDCFontChanger(); };