X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..107ea8f0694830232c7df4a1568b707111c04649:/interface/wx/dc.h diff --git a/interface/wx/dc.h b/interface/wx/dc.h index 391b9ebc70..e4d387bc6d 100644 --- a/interface/wx/dc.h +++ b/interface/wx/dc.h @@ -6,6 +6,77 @@ // 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 mode which can be used with wxDC::SetMapMode. +*/ +enum wxMappingMode +{ + /** Each logical unit is 1 device pixel. */ + wxMM_TEXT = 1, + + wxMM_LOMETRIC, + wxMM_HIMETRIC, + + /** Each logical unit is 1/10 of a mm. */ + wxMM_LOENGLISH, + + wxMM_HIENGLISH, + + /** Each logical unit is 1/20 of a point, or 1/1440 of an inch. */ + wxMM_TWIPS, + + wxMM_ISOTROPIC, + wxMM_ANISOTROPIC, + + /** Each logical unit is a point, or 1/72 of an inch. */ + wxMM_POINTS, + + /** Each logical unit is 1 mm. */ + wxMM_METRIC +}; + /** @class wxDC @@ -44,7 +115,8 @@ @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 @@ -107,11 +179,11 @@ 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. + @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 - -1, xsrc and ysrc will be assumed for the mask source position. + @c -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. @@ -120,8 +192,8 @@ public: */ 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); + wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, + wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); /** Adds the specified point to the bounding box which can be retrieved @@ -136,13 +208,6 @@ public: */ void Clear(); - /** - 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. - */ - virtual void ComputeScaleAndOrigin(); - /** 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 @@ -207,7 +272,7 @@ public: @see SetTextForeground(), SetTextBackground(), wxMemoryDC */ void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, - bool transparent); + bool useMask = false); //@{ /** @@ -273,10 +338,10 @@ public: 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); void DrawLabel(const wxString& text, const wxRect& rect, int alignment = wxALIGN_LEFT | wxALIGN_TOP, int indexAccel = -1); @@ -332,7 +397,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 @@ -353,7 +419,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 @@ -384,7 +450,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 @@ -445,7 +511,7 @@ 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 The current @ref GetLogicalFunction() "logical function" is + @note The current @ref GetLogicalFunction() "logical function" is ignored by this function. */ void DrawText(const wxString& text, wxCoord x, wxCoord y); @@ -476,14 +542,14 @@ 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() */ - const wxBrush GetBackground() const; + const wxBrush& GetBackground() const; /** Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. @@ -497,7 +563,7 @@ public: @see wxDC::SetBrush() */ - const wxBrush GetBrush() const; + const wxBrush& GetBrush() const; /** Gets the character height of the currently set font. @@ -517,7 +583,7 @@ 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. @@ -532,7 +598,7 @@ public: wxNullFont initially and only after calling SetFont() a valid font is returned. */ - const wxFont GetFont() const; + const wxFont& GetFont() const; /** Gets the current layout direction of the device context. On platforms @@ -549,14 +615,14 @@ public: @see SetLogicalFunction() */ - int GetLogicalFunction() const; + wxRasterOperationMode GetLogicalFunction() const; /** Gets the mapping mode for the device context. @see SetMapMode() */ - int GetMapMode() const; + wxMappingMode GetMapMode() const; /** Gets the dimensions of the string using the currently selected font. @@ -576,7 +642,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, @@ -588,7 +654,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 @@ -613,7 +679,7 @@ public: @see SetPen() */ - const wxPen GetPen() const; + const wxPen& GetPen() const; /** Gets in @a colour the colour at the specified location. Not available @@ -657,7 +723,7 @@ public: @endWxPythonOnly */ void GetSize(wxCoord* width, wxCoord* height) const; - const wxSize GetSize() const; + wxSize GetSize() const; //@} //@{ @@ -665,7 +731,7 @@ public: Returns the horizontal and vertical resolution in millimetres. */ void GetSizeMM(wxCoord* width, wxCoord* height) const; - const wxSize GetSizeMM() const; + wxSize GetSizeMM() const; //@} /** @@ -673,7 +739,7 @@ public: @see SetTextBackground() */ - const wxColour GetTextBackground() const; + const wxColour& GetTextBackground() const; //@{ /** @@ -706,7 +772,7 @@ public: wxCoord* descent = NULL, wxCoord* externalLeading = NULL, const wxFont* font = NULL) const; - const wxSize GetTextExtent(const wxString& string) const; + wxSize GetTextExtent(const wxString& string) const; //@} /** @@ -714,14 +780,14 @@ public: @see SetTextForeground() */ - const wxColour GetTextForeground() const; + const wxColour& GetTextForeground() const; /** Gets the current user scale factor. @see SetUserScale() */ - void GetUserScale(double x, double y); + void GetUserScale(double* x, double* y) const; //@{ /** @@ -752,15 +818,14 @@ public: 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, + void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, const wxColour& destColour, - wxDirection nDirection = wxEAST); + wxDirection nDirection = wxRIGHT); /** Returns @true if the DC is ok to use. */ - bool Ok(); + bool IsOk() const; /** Converts logical X coordinate to device coordinate, using the current @@ -905,46 +970,27 @@ public: void SetLayoutDirection(wxLayoutDirection dir); /** - 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 + 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. - 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 + 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(int function); + void SetLogicalFunction(wxRasterOperationMode function); /** 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 + 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. @@ -953,16 +999,8 @@ public: 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. */ - void SetMapMode(int mode); + void SetMapMode(wxMappingMode mode); /** If this is a window DC or memory DC, assigns the given palette to the @@ -1012,7 +1050,7 @@ public: /** Starts a document page (only relevant when outputting to a printer). */ - bool StartPage(); + void StartPage(); /** Copy from a source DC to this DC, specifying the destination @@ -1069,12 +1107,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. @@ -1090,9 +1128,10 @@ 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); }; @@ -1123,7 +1162,8 @@ public: @library{wxcore} @category{gdi} - @see wxDC::SetClippingRegion() + @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, + wxDCBrushChanger */ class wxDCClipper { @@ -1136,7 +1176,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(); };