/////////////////////////////////////////////////////////////////////////////
// Name: datstrm.h
-// Purpose: interface of wxDataOutputStream
+// Purpose: interface of wxDataInputStream and wxDataOutputStream
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@class wxDataOutputStream
@wxheader{datstrm.h}
- This class provides functions that write binary data types in a
- portable way. Data can be written in either big-endian or little-endian
- format, little-endian being the default on all architectures.
+ This class provides functions that write binary data types in a portable
+ way. Data can be written in either big-endian or little-endian format,
+ little-endian being the default on all architectures.
- If you want to write data to text files (or streams) use
- wxTextOutputStream instead.
+ If you want to write data to text files (or streams) use wxTextOutputStream
+ instead.
- The operator is overloaded and you can use this class like a standard
- C++ iostream. See wxDataInputStream for its
- usage and caveats.
-
- See also wxDataInputStream.
+ The "<<" operator is overloaded and you can use this class like a standard
+ C++ iostream. See wxDataInputStream for its usage and caveats.
@library{wxbase}
@category{streams}
+
+ @see wxDataInputStream
*/
class wxDataOutputStream
{
public:
- //@{
/**
- )
- Constructs a datastream object from an output stream. Only write methods will
- be available. The second form is only available in Unicode build of wxWidgets.
+ Constructs a datastream object from an output stream. Only write
+ methods will be available.
@param stream
The output stream.
- @param conv
- Charset conversion object object used to encoding Unicode
- strings before writing them to the stream
- in Unicode mode (see WriteString()
- documentation for detailed description). Note that you must not destroy
- conv before you destroy this wxDataOutputStream instance! It is
- recommended to use default value (UTF-8).
*/
wxDataOutputStream(wxOutputStream& stream);
- wxDataOutputStream(wxOutputStream& stream);
- //@}
+ /**
+ Constructs a datastream object from an output stream. Only write
+ methods will be available. This constructor is only available in
+ Unicode builds of wxWidgets.
+
+ @param stream
+ The output stream.
+ @param conv
+ Charset conversion object object used to encoding Unicode strings
+ before writing them to the stream in Unicode mode (see
+ WriteString() for a detailed description). Note that you must not
+ destroy @a conv before you destroy this wxDataOutputStream
+ instance! It is recommended to use the default value (UTF-8).
+ */
+ wxDataOutputStream(wxOutputStream& stream,
+ const wxMBConv& conv = wxConvAuto());
/**
Destroys the wxDataOutputStream object.
~wxDataOutputStream();
/**
- If @a be_order is @true, all data will be written in big-endian
- order, e.g. for reading on a Sparc or from Java-Streams (which
- always use big-endian order), otherwise data will be written in
- little-endian order.
+ If @a be_order is @true, all data will be written in big-endian order,
+ e.g. for reading on a Sparc or from Java-Streams (which always use
+ big-endian order), otherwise data will be written in little-endian
+ order.
*/
void BigEndianOrdered(bool be_order);
- //@{
+ /**
+ Writes the single byte @a i8 to the stream.
+ */
+ void Write8(wxUint8 i8);
+ /**
+ Writes an array of bytes to the stream. The amount of bytes to write is
+ specified with the @a size variable.
+ */
+ void Write8(const wxUint8* buffer, size_t size);
+
+ /**
+ Writes the 16 bit unsigned integer @a i16 to the stream.
+ */
+ void Write16(wxUint16 i16);
/**
Writes an array of 16 bit unsigned integer to the stream. The amount of
16 bit unsigned integer to write is specified with the @a size variable.
*/
- void Write16(wxUint16 i16);
void Write16(const wxUint16* buffer, size_t size);
- //@}
- //@{
+ /**
+ Writes the 32 bit unsigned integer @a i32 to the stream.
+ */
+ void Write32(wxUint32 i32);
/**
Writes an array of 32 bit unsigned integer to the stream. The amount of
32 bit unsigned integer to write is specified with the @a size variable.
*/
- void Write32(wxUint32 i32);
void Write32(const wxUint32* buffer, size_t size);
- //@}
- //@{
+ /**
+ Writes the 64 bit unsigned integer @a i64 to the stream.
+ */
+ void Write64(wxUint64 i64);
/**
Writes an array of 64 bit unsigned integer to the stream. The amount of
64 bit unsigned integer to write is specified with the @a size variable.
*/
- void Write64(wxUint64 i64);
void Write64(const wxUint64* buffer, size_t size);
- //@}
- //@{
/**
- Writes an array of bytes to the stream. The amount of bytes to write is
- specified with the @a size variable.
+ Writes the double @a f to the stream using the IEEE format.
*/
- void Write8(wxUint8 i8);
- void Write8(const wxUint8* buffer, size_t size);
- //@}
-
- //@{
+ void WriteDouble(double f);
/**
Writes an array of double to the stream. The amount of double to write is
specified with the @a size variable.
*/
- void WriteDouble(double f);
void WriteDouble(const double* buffer, size_t size);
- //@}
/**
- Writes @a string to the stream. Actually, this method writes the size of
- the string before writing @a string itself.
- In ANSI build of wxWidgets, the string is written to the stream in exactly
- same way it is represented in memory. In Unicode build, however, the string
- is first converted to multibyte representation with @e conv object passed
- to stream's constructor (consequently, ANSI application can read data
- written by Unicode application, as long as they agree on encoding) and this
- representation is written to the stream. UTF-8 is used by default.
+ Writes @a string to the stream. Actually, this method writes the size
+ of the string before writing @a string itself.
+
+ In ANSI build of wxWidgets, the string is written to the stream in
+ exactly same way it is represented in memory. In Unicode build,
+ however, the string is first converted to multibyte representation with
+ @e conv object passed to stream's constructor (consequently, ANSI
+ applications can read data written by Unicode application, as long as
+ they agree on encoding) and this representation is written to the
+ stream. UTF-8 is used by default.
*/
void WriteString(const wxString& string);
};
@class wxDataInputStream
@wxheader{datstrm.h}
- This class provides functions that read binary data types in a
- portable way. Data can be read in either big-endian or little-endian
- format, little-endian being the default on all architectures.
+ This class provides functions that read binary data types in a portable
+ way. Data can be read in either big-endian or little-endian format,
+ little-endian being the default on all architectures.
- If you want to read data from text files (or streams) use
- wxTextInputStream instead.
+ If you want to read data from text files (or streams) use wxTextInputStream
+ instead.
- The operator is overloaded and you can use this class like a standard C++
- iostream.
- Note, however, that the arguments are the fixed size types wxUint32, wxInt32 etc
- and on a typical 32-bit computer, none of these match to the "long" type
- (wxInt32
- is defined as signed int on 32-bit architectures) so that you cannot use long.
- To avoid
- problems (here and elsewhere), make use of the wxInt32, wxUint32, etc types.
+ The ">>" operator is overloaded and you can use this class like a standard
+ C++ iostream. Note, however, that the arguments are the fixed size types
+ wxUint32, wxInt32 etc and on a typical 32-bit computer, none of these match
+ to the "long" type (wxInt32 is defined as signed int on 32-bit
+ architectures) so that you cannot use long. To avoid problems (here and
+ elsewhere), make use of the wxInt32, wxUint32, etc types.
For example:
@code
wxFileInputStream input( "mytext.dat" );
- wxDataInputStream store( input );
- wxUint8 i1;
- float f2;
- wxString line;
-
- store i1; // read a 8 bit integer.
- store i1 f2; // read a 8 bit integer followed by float.
- store line; // read a text line
+ wxDataInputStream store( input );
+ wxUint8 i1;
+ float f2;
+ wxString line;
+
+ store >> i1; // read a 8 bit integer.
+ store >> i1 >> f2; // read a 8 bit integer followed by float.
+ store >> line; // read a text line
@endcode
- See also wxDataOutputStream.
-
@library{wxbase}
@category{streams}
+
+ @see wxDataOutputStream
*/
class wxDataInputStream
{
public:
- //@{
/**
- )
- Constructs a datastream object from an input stream. Only read methods will
- be available. The second form is only available in Unicode build of wxWidgets.
+ Constructs a datastream object from an input stream. Only read methods
+ will be available.
+
+ @param stream
+ The input stream.
+ */
+ wxDataInputStream(wxInputStream& stream);
+ /**
+ Constructs a datastream object from an input stream. Only read methods
+ will be available. This constructor is only available in Unicode builds
+ of wxWidgets.
@param stream
The input stream.
@param conv
Charset conversion object object used to decode strings in Unicode
- mode (see ReadString()
- documentation for detailed description). Note that you must not destroy
- conv before you destroy this wxDataInputStream instance!
+ mode (see ReadString() for a detailed description). Note that you
+ must not destroy @a conv before you destroy this wxDataInputStream
+ instance!
*/
- wxDataInputStream(wxInputStream& stream);
- wxDataInputStream(wxInputStream& stream);
- //@}
+ wxDataInputStream(wxInputStream& stream,
+ const wxMBConv& conv = wxConvAuto());
/**
Destroys the wxDataInputStream object.
~wxDataInputStream();
/**
- If @a be_order is @true, all data will be read in big-endian
- order, such as written by programs on a big endian architecture
- (e.g. Sparc) or written by Java-Streams (which always use
- big-endian order).
+ If @a be_order is @true, all data will be read in big-endian order,
+ such as written by programs on a big endian architecture (e.g. Sparc)
+ or written by Java-Streams (which always use big-endian order).
*/
void BigEndianOrdered(bool be_order);
- //@{
/**
- Reads 16 bit unsigned integers from the stream in a specified buffer. the
- amount of 16 bit unsigned integer to read is specified by the @a size variable.
+ Reads a single byte from the stream.
+ */
+ wxUint8 Read8();
+ /**
+ Reads bytes from the stream in a specified buffer. The amount of bytes
+ to read is specified by the @a size variable.
+ */
+ void Read8(wxUint8* buffer, size_t size);
+
+ /**
+ Reads a 16 bit unsigned integer from the stream.
*/
wxUint16 Read16();
+ /**
+ Reads 16 bit unsigned integers from the stream in a specified buffer.
+ The amount of 16 bit unsigned integers to read is specified by the
+ @a size variable.
+ */
void Read16(wxUint16* buffer, size_t size);
- //@}
- //@{
/**
- Reads 32 bit unsigned integers from the stream in a specified buffer. the
- amount of
- 32 bit unsigned integer to read is specified by the @a size variable.
+ Reads a 32 bit unsigned integer from the stream.
*/
wxUint32 Read32();
+ /**
+ Reads 32 bit unsigned integers from the stream in a specified buffer.
+ The amount of 32 bit unsigned integers to read is specified by the
+ @a size variable.
+ */
void Read32(wxUint32* buffer, size_t size);
- //@}
- //@{
/**
- Reads 64 bit unsigned integers from the stream in a specified buffer. the
- amount of
- 64 bit unsigned integer to read is specified by the @a size variable.
+ Reads a 64 bit unsigned integer from the stream.
*/
wxUint64 Read64();
- void Read64(wxUint64* buffer, size_t size);
- //@}
-
- //@{
/**
- Reads bytes from the stream in a specified buffer. The amount of
- bytes to read is specified by the @a size variable.
+ Reads 64 bit unsigned integers from the stream in a specified buffer.
+ The amount of 64 bit unsigned integers to read is specified by the
+ @a size variable.
*/
- wxUint8 Read8();
- void Read8(wxUint8* buffer, size_t size);
- //@}
+ void Read64(wxUint64* buffer, size_t size);
- //@{
/**
- Reads double data (IEEE encoded) from the stream in a specified buffer. the
- amount of
- double to read is specified by the @a size variable.
+ Reads a double (IEEE encoded) from the stream.
*/
double ReadDouble();
+ /**
+ Reads double data (IEEE encoded) from the stream in a specified buffer.
+ The amount of doubles to read is specified by the @a size variable.
+ */
void ReadDouble(double* buffer, size_t size);
- //@}
/**
- Reads a string from a stream. Actually, this function first reads a long
- integer specifying the length of the string (without the last null character)
- and then reads the string.
- In Unicode build of wxWidgets, the fuction first reads multibyte (char*)
- string from the stream and then converts it to Unicode using the @e conv
- object passed to constructor and returns the result as wxString. You are
- responsible for using the same convertor as when writing the stream.
- See also wxDataOutputStream::WriteString.
+ Reads a string from a stream. Actually, this function first reads a
+ long integer specifying the length of the string (without the last null
+ character) and then reads the string.
+
+ In Unicode build of wxWidgets, the fuction first reads multibyte
+ (char*) string from the stream and then converts it to Unicode using
+ the @e conv object passed to constructor and returns the result as
+ wxString. You are responsible for using the same convertor as when
+ writing the stream.
+
+ @see wxDataOutputStream::WriteString()
*/
wxString ReadString();
};
@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 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.
+ A wxDC is a @e "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.
Notice that wxDC is an abstract base class and can't be created directly,
- please use wxPaintDC, wxClientDC,
- wxWindowDC, wxScreenDC,
- wxMemoryDC or wxPrinterDC.
-
- Please note that in addition to the versions of the methods documented here,
- there are also versions which accept single @c wxPoint parameter instead of
- two @c wxCoord ones or @c wxPoint and @c wxSize instead of four of
- them.
-
- @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
-
+ please use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
+ wxPrinterDC.
+
+ Please note that in addition to the versions of the methods documented
+ here, there are also versions which accept single wxPoint parameter instead
+ of two wxCoord ones or wxPoint and wxSize instead of four of them.
+
+ @note Beginning with wxWidgets 2.9.0 the entire wxDC code has been
+ reorganized. All platform dependent code (actual all drawing code)
+ has been moved into backend classes which derive from a common
+ wxDCImpl class. The user-visible classes such as wxClientDC and
+ wxPaintDC merely forward all calls to the backend implementation.
+
+ @section dc_alpha Support for Transparency / Alpha Channel
+
+ On Mac OS X, when using Core Graphics (wxMAC_USE_CORE_GRAPHICS set to 1),
+ colors with alpha are supported. Instances wxPen or wxBrush that are built
+ from wxColour use the color's alpha values when stroking or filling.
@library{wxcore}
@category{dc,gdi}
- @see Overview()
+ @see @ref overview_dc
+
+ @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
{
/**
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.
+ logical function, whether to use a bitmap mask, and mask source
+ position.
@param xdest
Destination device context x position.
@param ysrc
Source device context y position.
@param logicalFunc
- Logical function to use: see SetLogicalFunction().
+ 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:
-
-
- Creates a temporary bitmap and copies the destination area into it.
- Copies the source area into the temporary bitmap using the specified
- logical function.
- 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.
- 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.
- ORs the temporary bitmap with the destination area.
- Deletes the temporary bitmap.
-
-
- This sequence of operations ensures that the source's transparent area need
- not be black,
- and logical functions are supported.
- 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 no-maskblt option to 1.
+ 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:
+ <ol>
+ <li>Creates a temporary bitmap and copies the destination area into
+ it.</li>
+ <li>Copies the source area into the temporary bitmap using the
+ specified logical function.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>ORs the temporary bitmap with the destination area.</li>
+ <li>Deletes the temporary bitmap.</li>
+ </ol>
+ 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.
+ 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.
+ 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.
+ @remarks There is partial support for Blit() in wxPostScriptDC, under X.
@see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
*/
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);
+ 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.
+ Adds the specified point to the bounding box which can be retrieved
+ with MinX(), MaxX() and MinY(), MaxY() functions.
@see ResetBoundingBox()
*/
/**
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.
+ 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 given point.
+ 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);
/**
Destroys the current clipping region so that none of the DC is clipped.
- See also SetClippingRegion().
+
+ @see SetClippingRegion()
*/
void DestroyClippingRegion();
virtual wxCoord DeviceToLogicalX(wxCoord x);
/**
- 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.
+ 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.
*/
virtual wxCoord DeviceToLogicalXRel(wxCoord x);
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.
+ 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.
*/
virtual wxCoord DeviceToLogicalYRel(wxCoord y);
/**
- Draws an arc of a circle, centred on (@e xc, yc), with starting point (@e x1,
- y1)
- and ending at (@e x2, y2). 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.
+ Draws an arc of a circle, centred on (@a xc, @a yc), with starting
+ point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
+ used for the outline and the current brush for filling the shape.
+
+ The arc is drawn in a counter-clockwise direction from the start point
+ 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 @a transparent
- is @true and the bitmap has
- a transparency mask, 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 also SetTextForeground(),
- SetTextBackground() and wxMemoryDC.
+ Draw a bitmap on the device context at the specified point. If
+ @a transparent is @true and the bitmap has a transparency mask, 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(), wxMemoryDC
*/
void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
- bool transparent);
+ bool transparent);
//@{
/**
Draws a check mark inside the given rectangle.
*/
- void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width,
- wxCoord height);
+ void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
void DrawCheckMark(const wxRect& rect);
//@}
//@{
/**
- Draws an ellipse contained in the rectangle specified either with the given top
- left corner and the given size or directly. The current pen is used for the
- outline and the current brush for filling the shape.
+ Draws an ellipse contained in the rectangle specified either with the
+ given top left corner and the given size or directly. 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);
+ void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
void DrawEllipse(const wxPoint& pt, const wxSize& size);
void DrawEllipse(const wxRect& rect);
//@}
/**
- Draws an arc of an ellipse. The current pen is used for drawing the arc and
- the current brush is used for drawing the pie.
- @a x and @a y specify the x and y coordinates of the upper-left corner of the
- rectangle that contains
- the ellipse.
- @a width and @a height specify the width and height of the rectangle that
- contains
- the ellipse.
- @a start and @a end 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 @a start is equal to @e end, a
- complete ellipse will be drawn.
+ Draws an arc of an ellipse. The current pen is used for drawing the arc
+ and the current brush is used for drawing the pie.
+
+ @a x and @a y specify the x and y coordinates of the upper-left corner
+ of the rectangle that contains the ellipse.
+
+ @a width and @a height specify the width and height of the rectangle
+ that contains the ellipse.
+
+ @a start and @a end 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 @a start is equal to @e end, a complete
+ ellipse will be drawn.
*/
- void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width,
- wxCoord height,
- double start,
- double end);
+ void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
+ double start, double end);
/**
- 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.
+ 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);
//@{
/**
- 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.
+ 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,
+ virtual void DrawLabel(const wxString& text, const wxBitmap& image,
const wxRect& rect,
int alignment = wxALIGN_LEFT | wxALIGN_TOP,
- int indexAccel = -1,
- wxRect* rectBounding = NULL);
+ int indexAccel = -1, wxRect* rectBounding = NULL);
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 used
- for drawing the line. Note that the point (x2, y2) is not part of the
- line and is not drawn by this function (this is consistent with the behaviour
- of many other toolkits).
+ Draws a line from the first point to the second. The current pen is
+ used for drawing the line. Note that the point (@a x2, @a y2) 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);
- //@{
/**
- This method uses a list of wxPoints, adding the optional offset
- coordinate. The programmer is responsible for deleting the list
- of points.
+ Draws lines using an array of points of size @a n adding the optional
+ offset coordinate. The current pen is used for drawing the lines.
+
+ @beginWxPythonOnly
+ The wxPython version of this method accepts a Python list of wxPoint
+ objects.
+ @endWxPythonOnly
*/
void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
wxCoord yoffset = 0);
+ /**
+ This method uses a list of wxPoints, adding the optional offset
+ coordinate. The programmer is responsible for deleting the list of
+ points.
+
+ @beginWxPythonOnly
+ The wxPython version of this method accepts a Python list of wxPoint
+ objects.
+ @endWxPythonOnly
+ */
void DrawLines(const wxPointList* points,
- wxCoord xoffset = 0,
- wxCoord yoffset = 0);
- //@}
+ wxCoord xoffset = 0, wxCoord yoffset = 0);
/**
Draws a point using the color of the current pen. Note that the other
- properties of the pen are not used, such as width etc..
+ properties of the pen are not used, such as width.
*/
void DrawPoint(wxCoord x, wxCoord y);
/**
- Draws two or more filled polygons using an array of @e points, adding the
- optional offset coordinates.
- Notice that for the platforms providing a native implementation
- of this function (Windows and PostScript-based wxDC currently), this is more
- efficient than using DrawPolygon() in a loop.
- @a n specifies the number of polygons to draw, the array @e count of size
- @a n specifies the number of points in each of the polygons in the
- @e points array.
- The last argument specifies the fill rule: @b wxODDEVEN_RULE (the default)
- or @b wxWINDING_RULE.
- The current pen is used for drawing the outline, and the current brush for
- filling the shape. Using a transparent brush suppresses filling.
- The polygons maybe disjoint or overlapping. Each polygon specified in a call to
- @b DrawPolyPolygon must be closed. Unlike polygons created by the
- DrawPolygon() member function, the polygons created by
- @b DrawPolyPolygon are not closed automatically.
- */
- void DrawPolyPolygon(int n, int count[], wxPoint points[],
- wxCoord xoffset = 0,
- wxCoord yoffset = 0,
- int fill_style = wxODDEVEN_RULE);
+ Draws a filled polygon using an array of points of size @a n, adding
+ the optional offset coordinate. The first and last points are
+ automatically closed.
- //@{
+ The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
+ default) or @b wxWINDING_RULE.
+
+ The current pen is used for drawing the outline, and the current brush
+ 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);
/**
- This method draws a filled polygon using a list of wxPoints,
- adding the optional offset coordinate.
+ This method draws a filled polygon using a list of wxPoints, adding the
+ optional offset coordinate. The first and last points are automatically
+ closed.
+
The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
default) or @b wxWINDING_RULE.
+
The current pen is used for drawing the outline, and the current brush
- for filling the shape. Using a transparent brush suppresses filling.
+ for filling the shape. Using a transparent brush suppresses filling.
+
The programmer is responsible for deleting the list of points.
- Note that wxWidgets automatically closes the first and last points.
+
+ @beginWxPythonOnly
+ The wxPython version of this method accepts a Python list of wxPoint
+ objects.
+ @endWxPythonOnly
*/
- void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
- wxCoord yoffset = 0,
- int fill_style = wxODDEVEN_RULE);
void DrawPolygon(const wxPointList* points,
- wxCoord xoffset = 0,
- wxCoord yoffset = 0,
+ wxCoord xoffset = 0, wxCoord yoffset = 0,
int fill_style = wxODDEVEN_RULE);
- //@}
+
+ /**
+ Draws two or more filled polygons using an array of @a points, adding
+ the optional offset coordinates.
+
+ Notice that for the platforms providing a native implementation of this
+ function (Windows and PostScript-based wxDC currently), this is more
+ efficient than using DrawPolygon() in a loop.
+
+ @a n specifies the number of polygons to draw, the array @e count of
+ size @a n specifies the number of points in each of the polygons in the
+ @a points array.
+
+ The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
+ default) or @b wxWINDING_RULE.
+
+ The current pen is used for drawing the outline, and the current brush
+ for filling the shape. Using a transparent brush suppresses filling.
+
+ The polygons maybe disjoint or overlapping. Each polygon specified in a
+ call to DrawPolyPolygon() must be closed. Unlike polygons created by
+ the DrawPolygon() member function, the polygons created by this
+ method are not closed automatically.
+
+ @beginWxPythonOnly
+ Not implemented yet.
+ @endWxPythonOnly
+ */
+ void DrawPolyPolygon(int n, int count[], wxPoint points[],
+ wxCoord xoffset = 0, wxCoord yoffset = 0,
+ int fill_style = wxODDEVEN_RULE);
/**
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);
+ void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
/**
Draws the text rotated by @a angle 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 as the
- latter is not a TrueType font. @c wxSWISS_FONT is an example of a font
- which is.
+ particular, a font different from @c wxNORMAL_FONT should be used
+ as the latter is not a TrueType font. @c wxSWISS_FONT is an
+ example of a font which is.
@see DrawText()
*/
/**
Draws a rectangle with the given top left corner, and with the given
- size. The corners are quarter-circles using the given radius. The
+ 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 @a radius is positive, the value is assumed to be the
- radius of the rounded corner. If @a radius is negative,
- the absolute value is assumed to be the @e 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.
+
+ If @a radius is positive, the value is assumed to be the radius of the
+ rounded corner. If @a radius is negative, the absolute value is assumed
+ to be the @e 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);
+ wxCoord height, double radius);
//@{
/**
- Draws a three-point spline using the current pen.
+ Draws a spline between all given points using the current pen.
+
+ @beginWxPythonOnly
+ The wxPython version of this method accepts a Python list of wxPoint
+ objects.
+ @endWxPythonOnly
*/
void DrawSpline(int n, wxPoint points[]);
void DrawSpline(const wxPointList* points);
- void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2,
- wxCoord y2,
- wxCoord x3,
- wxCoord y3);
+ 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 font,
- and the current text foreground and background colours.
+ 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
- @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.
+ 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.
*/
void DrawText(const wxString& text, wxCoord x, wxCoord y);
/**
Flood fills the device context starting from the given point, using
- the @e 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.
- @e 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.
+ 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& colour,
int style = wxFLOOD_SURFACE);
/**
- Gets the brush used for painting the background (see wxDC::SetBackground).
+ Gets the brush used for painting the background.
+
+ @see wxDC::SetBackground()
*/
const wxBrush GetBackground() const;
int GetBackgroundMode() const;
/**
- Gets the current brush (see wxDC::SetBrush).
+ Gets the current brush.
+
+ @see wxDC::SetBrush()
*/
const wxBrush GetBrush() const;
/**
Gets the rectangle surrounding the current clipping region.
+
+ @beginWxPythonOnly
+ No arguments are required and the four values defining the rectangle
+ 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);
/**
Returns the depth (number of bits/pixel) of this DC.
int GetDepth() const;
/**
- Gets the current font. Notice that even although each device context object has
- some default font after creation, this method would return a @c wxNullFont
- initially and only after calling SetFont() a valid
- font is returned.
+ 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.
*/
const wxFont GetFont() const;
/**
- 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.
+ 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()
*/
wxLayoutDirection GetLayoutDirection() const;
/**
- Gets the current logical function (see wxDC::SetLogicalFunction).
+ Gets the current logical function.
+
+ @see SetLogicalFunction()
*/
int GetLogicalFunction();
/**
- Gets the @e mapping mode for the device context (see wxDC::SetMapMode).
+ Gets the mapping mode for the device context.
+
+ @see SetMapMode()
*/
int GetMapMode();
- //@{
/**
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.
- The text extent is returned in @a w and @a h pointers (first form) or as
- a wxSize object (second form).
- If the optional parameter @a font is specified and valid, then it is used
- for the text extent calculation. Otherwise the currently selected font is.
- Note that this function works both with single-line and multi-line strings.
+
+ The text extent is set in the given @a w and @a h pointers.
+
+ If the optional parameter @a font is specified and valid, then it is
+ used for the text extent calculation, otherwise the currently selected
+ font is used.
+
+ @note This function works with both single-line and multi-line strings.
@see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
*/
wxCoord* h,
wxCoord* heightLine = NULL,
wxFont* font = NULL) const;
- const wxSize GetMultiLineTextExtent(const wxString& string) const;
- //@}
-
/**
- Returns the resolution of the device in pixels per inch.
+ 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.
+
+ @returns The text extent as a wxSize object.
+
+ @note This function works with both single-line and multi-line strings.
+
+ @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
*/
- wxSize GetPPI() const;
+ const wxSize GetMultiLineTextExtent(const wxString& string) const;
/**
- Fills the @a widths array with the widths from the beginning of
- @a text to the corresponding character of @e 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 should be used
- instead.
+ Fills the @a widths array with the widths from the beginning of @a text
+ to the corresponding character of @a 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 should be used instead.
+
+ @beginWxPythonOnly
+ This method only takes the @a text parameter and returns a Python list
+ of integers.
+ @endWxPythonOnly
@see GetMultiLineTextExtent(), GetTextExtent()
*/
wxArrayInt& widths) const;
/**
- Gets the current pen (see wxDC::SetPen).
+ 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 that setting a pixel can be done using DrawPoint().
+ 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);
- //@{
/**
- 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:
-
+ Returns the resolution of the device in pixels per inch.
+ */
+ wxSize GetPPI() const;
- @b GetSize()
+ //@{
+ /**
+ This gets the horizontal and vertical resolution in device units. It
+ can be used to scale graphics to fit the page.
- Returns a Wx::Size
+ 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:
- @b GetSizeWH()
+ @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
- Returns a 2-element list
- @c ( width, height )
+ @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;
+ const wxSize GetSize() const;
//@}
//@{
Returns the horizontal and vertical resolution in millimetres.
*/
void GetSizeMM(wxCoord* width, wxCoord* height) const;
- const wxSize GetSizeMM() const;
+ const wxSize GetSizeMM() const;
//@}
/**
- Gets the current text background colour (see wxDC::SetTextBackground).
+ 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 from the baseline of the font to the bottom of the
- descender, and @a externalLeading is any extra vertical space added
- to the font by the font designer (usually is zero).
- The text extent is returned in @a w and @a h pointers (first form) or as
- a wxSize object (second form).
- If the optional parameter @a font is specified and valid, then it is used
- for the text extent calculation. Otherwise the currently selected font is.
- Note that this function only works with single-line strings.
+ @a string is the text string to measure, @a descent is the dimension
+ from the baseline of the font to the bottom of the descender, and
+ @a externalLeading is any extra vertical space added to the font by the
+ font designer (usually is zero).
+
+ The text extent is returned in @a w and @a h pointers or as a wxSize
+ object depending on which version of this function is used.
+
+ If the optional parameter @a font is specified and valid, then it is
+ used for the text extent calculation. Otherwise the currently selected
+ font is.
+
+ @note This function only works with single-line strings.
+
+ @beginWxPythonOnly
+ The following methods are implemented in wxPython:
+ - GetTextExtent(string) - Returns a 2-tuple, (width, height).
+ - GetFullTextExtent(string, font=NULL) -
+ Returns a 4-tuple, (width, height, descent, externalLeading).
+ @endWxPythonOnly
@see wxFont, SetFont(), GetPartialTextExtents(),
GetMultiLineTextExtent()
*/
- void GetTextExtent(const wxString& string, wxCoord* w,
- wxCoord* h,
+ void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
wxCoord* descent = NULL,
wxCoord* externalLeading = NULL,
const wxFont* font = NULL) const;
//@}
/**
- Gets the current text foreground colour (see wxDC::SetTextForeground).
+ Gets the current text foreground colour.
+
+ @see SetTextForeground()
*/
const wxColour GetTextForeground() const;
/**
- Gets the current user scale factor (set by wxDC::SetUserScale).
+ 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.
+ @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 @e rect. If not specified, the cercle is placed at the
+ the specified @e rect. If not specified, the circle is placed at the
centre of rect.
- @note Currently this function is very slow, don't use it for
- real-time drawing.
+
+ @note Currently this function is very slow, don't use it for real-time
+ drawing.
*/
void GradientFillConcentric(const wxRect& rect,
const wxColour& initialColour,
//@}
/**
- 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
+ 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,
virtual wxCoord LogicalToDeviceX(wxCoord x);
/**
- 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.
+ 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.
*/
virtual wxCoord LogicalToDeviceXRel(wxCoord x);
virtual wxCoord LogicalToDeviceY(wxCoord y);
/**
- 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.
+ 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.
*/
virtual wxCoord LogicalToDeviceYRel(wxCoord y);
wxCoord MinY();
/**
- Resets the bounding box: after a call to this function, the bounding box
- doesn't contain anything.
+ Resets the bounding box: after a call to this function, the bounding
+ box doesn't contain anything.
@see CalcBoundingBox()
*/
/**
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.
+ 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.
+ 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.
+ True to set the y axis orientation to the natural bottom up
+ orientation, @false to invert it.
*/
void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
void SetBackground(const wxBrush& brush);
/**
- @a mode may be one of wxSOLID and wxTRANSPARENT. This setting determines
- whether text will be drawn with a background colour or not.
+ @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
+ determines whether text will be drawn with a background colour or not.
*/
void SetBackgroundMode(int mode);
/**
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 also wxBrush.
- See also wxMemoryDC for the interpretation of colours
- when drawing into a monochrome bitmap.
+
+ 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 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.
+ 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(), wxRegion
*/
//@}
/**
- Sets the device origin (i.e., the origin in pixels after scaling has been
- applied).
- This function may be useful in Windows printing
+ 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 font for the DC. It must be a valid font, in particular you
- should not pass @c wxNullFont to this method.
- See also wxFont.
+ 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
*/
void SetFont(const wxFont& font);
/**
- Sets the current layout direction for the device context. @a dir may be either
- @c wxLayout_Default, @c wxLayout_LeftToRight or @c wxLayout_RightToLeft.
+ 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()
*/
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 wxDC::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:
-
- 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.
+ 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.
*/
void SetLogicalFunction(int function);
/**
- The @e 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 @e user scale (see
- wxDC::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.
- 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
+ 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.
- 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.
+ The coordinate origin is always at the top left of the screen/printer.
- wxMM_TEXT
+ Drawing to a Windows printer device context uses the current mapping
+ mode, but mapping mode is currently ignored for PostScript output.
- Each logical unit is 1 device pixel.
+ 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 int);
+ 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 for further details.
+ 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 also wxMemoryDC for the interpretation of colours
- when drawing into a monochrome bitmap.
+ 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 foreground colour for the DC.
- See also wxMemoryDC for the interpretation of colours
- when drawing into a monochrome bitmap.
+
+ @see wxMemoryDC for the interpretation of colours when drawing into a
+ monochrome bitmap.
*/
void SetTextForeground(const wxColour& colour);
/**
Starts a document (only relevant when outputting to a printer).
- Message is a message to show while printing.
+ @a message is a message to show while printing.
*/
bool StartDoc(const wxString& message);
/**
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,
+ 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
@param srcHeight
Height of source area to be copied.
@param logicalFunc
- Logical function to use: see SetLogicalFunction().
+ 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:
-
-
- Creates a temporary bitmap and copies the destination area into it.
- Copies the source area into the temporary bitmap using the specified
- logical function.
- 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 background colour set to BLACK.
- 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.
- ORs the temporary bitmap with the destination area.
- Deletes the temporary bitmap.
-
-
- This sequence of operations ensures that the source's transparent area need
- not be black,
- and logical functions are supported.
- 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 no-maskblt option to 1.
+ 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:
+ <ol>
+ <li>Creates a temporary bitmap and copies the destination area into
+ it.</li>
+ <li>Copies the source area into the temporary bitmap using the
+ specified logical function.</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>ORs the temporary bitmap with the destination area.</li>
+ <li>Deletes the temporary bitmap.</li>
+ </ol>
+ 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.
+ 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.
- */
- bool StretchBlit(wxCoord xdest, wxCoord ydest, wxCoord dstWidth,
- wxCoord dstHeight,
- wxDC* source, wxCoord xsrc,
- wxCoord ysrc,
- wxCoord srcWidth,
- wxCoord srcHeight,
+ 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.
+
+ There is partial support for Blit() in wxPostScriptDC, under X.
+
+ StretchBlit() is only implemented under wxMAC and wxMSW.
+
+ See wxMemoryDC for typical usage.
+
+ @wxsince{2.9.0}
+
+ @see Blit(), wxMemoryDC, wxBitmap, wxMask
+ */
+ bool StretchBlit(wxCoord xdest, wxCoord ydest,
+ wxCoord dstWidth, wxCoord dstHeight,
+ wxDC* source, wxCoord xsrc, wxCoord ysrc,
+ wxCoord srcWidth, wxCoord srcHeight,
int logicalFunc = wxCOPY,
bool useMask = false,
- wxCoord xsrcMask = -1,
- wxCoord ysrcMask = -1);
+ wxCoord xsrcMask = -1, wxCoord ysrcMask = -1);
};
@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 created on the stack so that it is automatically destroyed
- when the object goes out of scope. A typical usage example:
+ 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
+ created on the stack so that it is automatically destroyed when the object
+ goes out of scope. A typical usage example:
@code
void MyFunction(wxDC& dc)
- {
- wxDCClipper clip(rect);
- ... drawing functions here are affected by clipping rect ...
- }
-
- void OtherFunction()
- {
- wxDC dc;
- MyFunction(dc);
- ... drawing functions here are not affected by clipping rect ...
- }
+ {
+ wxDCClipper clip(dc, rect);
+ // ... drawing functions here are affected by clipping rect ...
+ }
+
+ void OtherFunction()
+ {
+ wxDC dc;
+ MyFunction(dc);
+ // ... drawing functions here are not affected by clipping rect ...
+ }
@endcode
@library{wxcore}
@category{gdi}
- @see wxDC::SetClippingRegion
+ @see wxDC::SetClippingRegion()
*/
class wxDCClipper
{
public:
//@{
/**
- Sets the clipping region to the specified region @a r or rectangle specified
- by either a single @a rect parameter or its position (@a x and @e y)
- and size (@a w ad @e h).
+ Sets the clipping region to the specified region/coordinates.
+
The clipping region is automatically unset when this object is destroyed.
*/
wxDCClipper(wxDC& dc, const wxRegion& r);
projects / wxWidgets.git / commitdiff
