ALIASES += wxheader{1}="\headerfile \1 wx/\1"
# the following alias avoids to repeat lots of times the same statement:
-ALIASES += wxsince{1}="\since This function is new since wxWidgets version \1."
+ALIASES += wxsince{1}="\since This feature is available in wxWidgets version \1 or higher."
# some formatting aliases
ALIASES += true="<span class='literal'>true</span>"
@c "docs/xxx/install.txt" in your distribution, where @c "xxx" is the platform
of interest, such as @c msw, @c gtk, @c x11, @c mac.
-All wxWidgets makefiles are generated using
-@link http://www.bakefile.org Bakefile @endlink. wxWidgets also provides (in
-the @c "build/bakefiles/wxpresets" folder) the wxWidgets bakefile presets.
-These files allow you to create bakefiles for your own wxWidgets-based
-applications very easily.
+All wxWidgets makefiles are generated using Bakefile <http://www.bakefile.org/>.
+wxWidgets also provides (in the @c "build/bakefiles/wxpresets" folder) the
+wxWidgets bakefile presets. These files allow you to create bakefiles for your
+own wxWidgets-based applications very easily.
/////////////////////////////////////////////////////////////////////////////
// Name: dcclient.h
-// Purpose: interface of wxPaintDC
+// Purpose: interface of wxClientDC and wxPaintDC
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@wxheader{dcclient.h}
A wxPaintDC must be constructed if an application wishes to paint on the
- client area of a window from within an @b OnPaint event.
- This should normally be constructed as a temporary stack object; don't store
- a wxPaintDC object. If you have an OnPaint handler, you @e must create a
- wxPaintDC
- object within it even if you don't actually use it.
+ client area of a window from within an EVT_PAINT() event handler. This
+ should normally be constructed as a temporary stack object; don't store a
+ wxPaintDC object. If you have an EVT_PAINT() handler, you @e must create a
+ wxPaintDC object within it even if you don't actually use it.
- Using wxPaintDC within OnPaint is important because it automatically
- sets the clipping area to the damaged area of the window. Attempts to draw
- outside this area do not appear.
+ Using wxPaintDC within your EVT_PAINT() handler is important because it
+ automatically sets the clipping area to the damaged area of the window.
+ Attempts to draw outside this area do not appear.
- To draw on a window from outside @b OnPaint, construct a wxClientDC object.
+ To draw on a window from outside your EVT_PAINT() handler, construct a
+ wxClientDC object.
- To draw on the whole window including decorations, construct a wxWindowDC object
- (Windows only).
+ To draw on the whole window including decorations, construct a wxWindowDC
+ object (Windows only).
@library{wxcore}
@category{dc}
- @see wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC
+ @see wxDC, wxClientDC, wxMemoryDC, wxWindowDC, wxScreenDC
*/
class wxPaintDC : public wxWindowDC
{
@wxheader{dcclient.h}
A wxClientDC must be constructed if an application wishes to paint on the
- client area of a window from outside an @b OnPaint event.
- This should normally be constructed as a temporary stack object; don't store
- a wxClientDC object.
+ client area of a window from outside an EVT_PAINT() handler. This should
+ normally be constructed as a temporary stack object; don't store a
+ wxClientDC object.
- To draw on a window from within @b OnPaint, construct a wxPaintDC object.
+ To draw on a window from within an EVT_PAINT() handler, construct a
+ wxPaintDC object instead.
- To draw on the whole window including decorations, construct a wxWindowDC object
- (Windows only).
+ To draw on the whole window including decorations, construct a wxWindowDC
+ object (Windows only).
@library{wxcore}
@category{dc}
@wxheader{dcclient.h}
A wxWindowDC must be constructed if an application wishes to paint on the
- whole area of a window (client and decorations).
- This should normally be constructed as a temporary stack object; don't store
- a wxWindowDC object.
+ whole area of a window (client and decorations). This should normally be
+ constructed as a temporary stack object; don't store a wxWindowDC object.
- To draw on a window from inside @b OnPaint, construct a wxPaintDC object.
-
- To draw on the client area of a window from outside @b OnPaint, construct a
- wxClientDC object.
+ To draw on a window from inside an EVT_PAINT() handler, construct a
+ wxPaintDC object instead.
- To draw on the whole window including decorations, construct a wxWindowDC object
- (Windows only).
+ To draw on the client area of a window from outside an EVT_PAINT() handler,
+ construct a wxClientDC object.
@library{wxcore}
@category{dc}
@class wxMemoryDC
@wxheader{dcmemory.h}
- A memory device context provides a means to draw graphics onto a bitmap. When
- drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and
- @c wxWHITE_BRUSH
- will draw the background colour (i.e. 0) whereas all other colours will draw the
- foreground colour (i.e. 1).
+ A memory device context provides a means to draw graphics onto a bitmap.
+ When drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and
+ @c wxWHITE_BRUSH will draw the background colour (i.e. 0) whereas all other
+ colours will draw the foreground colour (i.e. 1).
+
+ A bitmap must be selected into the new memory DC before it may be used for
+ anything. Typical usage is as follows:
+
+ @code
+ // Create a memory DC
+ wxMemoryDC temp_dc;
+ temp_dc.SelectObject(test_bitmap);
+
+ // We can now draw into the memory DC...
+ // Copy from this DC to another DC.
+ old_dc.Blit(250, 50, BITMAP_WIDTH, BITMAP_HEIGHT, temp_dc, 0, 0);
+ @endcode
+
+ Note that the memory DC must be deleted (or the bitmap selected out of it)
+ before a bitmap can be reselected into another memory DC.
+
+ And, before performing any other operations on the bitmap data, the bitmap
+ must be selected out of the memory DC:
+
+ @code
+ temp_dc.SelectObject(wxNullBitmap);
+ @endcode
+
+ This happens automatically when wxMemoryDC object goes out of scope.
@library{wxcore}
@category{dc}
class wxMemoryDC : public wxDC
{
public:
- //@{
/**
- Constructs a new memory device context and calls SelectObject()
- with the given bitmap.
- Use the wxDC::IsOk member to test whether the constructor was successful
- in creating a usable device context.
+ Constructs a new memory device context.
+
+ Use the wxDC::Ok() member to test whether the constructor was
+ successful in creating a usable device context. Don't forget to select
+ a bitmap into the DC before drawing on it.
*/
wxMemoryDC();
+ /**
+ Constructs a new memory device context and calls SelectObject() with
+ the given bitmap.
+
+ Use the wxDC::Ok() member to test whether the constructor was
+ successful in creating a usable device context.
+ */
wxMemoryDC(wxBitmap& bitmap);
- //@}
/**
- Works exactly like SelectObjectAsSource() but
- this is the function you should use when you select a bitmap because you want
- to modify
- it, e.g. drawing on this DC.
- Using SelectObjectAsSource() when modifying
- the bitmap may incurr some problems related to wxBitmap being a reference
- counted object
- (see @ref overview_trefcount "reference counting overview").
- Also, before using the updated bitmap data, make sure to select it out of
- context first
- (for example by selecting wxNullBitmap into the device context).
-
- @see wxDC::DrawBitmap
+ Works exactly like SelectObjectAsSource() but this is the function you
+ should use when you select a bitmap because you want to modify it, e.g.
+ drawing on this DC.
+
+ Using SelectObjectAsSource() when modifying the bitmap may incurr some
+ problems related to wxBitmap being a reference counted object (see
+ @ref overview_refcount).
+
+ Also, before using the updated bitmap data, make sure to select it out
+ of context first (for example by selecting wxNullBitmap into the device
+ context).
+
+ @see wxDC::DrawBitmap()
*/
void SelectObject(wxBitmap& bitmap);
/**
Selects the given bitmap into the device context, to use as the memory
bitmap. Selecting the bitmap into a memory DC allows you to draw into
- the DC (and therefore the bitmap) and also to use wxDC::Blit to copy
- the bitmap to a window. For this purpose, you may find wxDC::DrawIcon
+ the DC (and therefore the bitmap) and also to use wxDC::Blit() to copy
+ the bitmap to a window. For this purpose, you may find wxDC::DrawIcon()
easier to use instead.
- If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the
- current bitmap is
- selected out of the device context, and the original bitmap restored, allowing
- the current bitmap to
- be destroyed safely.
+
+ If the argument is wxNullBitmap (or some other uninitialised wxBitmap)
+ the current bitmap is selected out of the device context, and the
+ original bitmap restored, allowing the current bitmap to be destroyed
+ safely.
*/
void SelectObjectAsSource(const wxBitmap& bitmap);
};
@wxheader{dcmirror.h}
wxMirrorDC is a simple wrapper class which is always associated with a real
- wxDC object and either forwards all of its operations to it
- without changes (no mirroring takes place) or exchanges @e x and @e y
- coordinates which makes it possible to reuse the same code to draw a figure and
- its mirror -- i.e. reflection related to the diagonal line x == y.
+ wxDC object and either forwards all of its operations to it without changes
+ (no mirroring takes place) or exchanges @e x and @e y coordinates which
+ makes it possible to reuse the same code to draw a figure and its mirror --
+ i.e. reflection related to the diagonal line x == y.
- wxMirrorDC has been added in wxWidgets version 2.5.0.
+ @wxsince{2.5.0}
@library{wxcore}
@category{dc}
{
public:
/**
- Creates a (maybe) mirrored DC associated with the real @e dc. Everything
- drawn on wxMirrorDC will appear (and maybe mirrored) on @e dc.
+ Creates a (maybe) mirrored DC associated with the real @a dc.
+ Everything drawn on wxMirrorDC will appear (and maybe mirrored) on
+ @a dc.
+
@a mirror specifies if we do mirror (if it is @true) or not (if it is
@false).
*/
@class wxPrinterDC
@wxheader{dcprint.h}
- A printer device context is specific to MSW and Mac, and allows access to any
- printer with a Windows or Macintosh driver. See wxDC for further
- information on device contexts, and wxDC::GetSize for
- advice on achieving the correct scaling for the page.
+ A printer device context is specific to MSW and Mac, and allows access to
+ any printer with a Windows or Macintosh driver. See wxDC for further
+ information on device contexts, and wxDC::GetSize() for advice on achieving
+ the correct scaling for the page.
@library{wxcore}
@category{printing}
- @see @ref overview_printingoverview "Printing framework overview", wxDC
+ @see @ref overview_printing, wxDC
*/
class wxPrinterDC : public wxDC
{
public:
- //@{
/**
- Constructor. With empty strings for the first three arguments, the default
- printer dialog is
- displayed. @a device indicates the type of printer and @e output
- is an optional file for printing to. The @a driver parameter is
- currently unused. Use the @e Ok member to test whether the
- constructor was successful in creating a usable device context.
- This constructor is deprecated and retained only for backward compatibility.
+ Constructor. Pass a wxPrintData object with information necessary for
+ setting up a suitable printer device context. This is the recommended
+ way to construct a wxPrinterDC. Make sure you specify a reference to a
+ wxPrintData object, not a pointer - you may not even get a warning if
+ you pass a pointer instead.
*/
wxPrinterDC(const wxPrintData& printData);
+ /**
+ Constructor. With empty strings for the first three arguments, the
+ default printer dialog is displayed. @a device indicates the type of
+ printer and @a output is an optional file for printing to. The
+ @a driver parameter is currently unused. Use the wxDC::Ok() member to
+ test whether the constructor was successful in creating a usable device
+ context.
+
+ @deprecated This constructor is deprecated and retained only for
+ backward compatibility.
+ */
wxPrinterDC(const wxString& driver, const wxString& device,
- const wxString& output,
- const bool interactive = true,
+ const wxString& output, const bool interactive = true,
int orientation = wxPORTRAIT);
- //@}
/**
- Return the rectangle in device coordinates that corresponds to the full paper
- area, including the nonprinting regions of the paper. The point (0,0) in device
- coordinates is the top left corner of the page rectangle, which is the printable
- area on MSW and Mac. The coordinates of the top left corner of the paper
- rectangle will therefore have small negative values, while the bottom right
- coordinates will be somewhat larger than the values returned by
- wxDC::GetSize.
+ Return the rectangle in device coordinates that corresponds to the full
+ paper area, including the nonprinting regions of the paper. The point
+ (0,0) in device coordinates is the top left corner of the page
+ rectangle, which is the printable area on MSW and Mac. The coordinates
+ of the top left corner of the paper rectangle will therefore have small
+ negative values, while the bottom right coordinates will be somewhat
+ larger than the values returned by wxDC::GetSize().
*/
wxRect wxPrinterDC::GetPaperRect();
};
@class wxPostScriptDC
@wxheader{dcps.h}
- This defines the wxWidgets Encapsulated PostScript device context,
- which can write PostScript files on any platform. See wxDC for
- descriptions of the member functions.
+ This defines the wxWidgets Encapsulated PostScript device context, which
+ can write PostScript files on any platform. See wxDC for descriptions of
+ the member functions.
@library{wxbase}
@category{dc}
class wxPostScriptDC : public wxDC
{
public:
- //@{
+ /**
+ Constructs a PostScript printer device context from a wxPrintData
+ object.
+ */
+ wxPostScriptDC(const wxPrintData& printData);
/**
Constructor. @a output is an optional file for printing to, and if
@a interactive is @true a dialog box will be displayed for adjusting
various parameters. @a parent is the parent of the printer dialog box.
- Use the @e Ok member to test whether the constructor was successful
- in creating a usable device context.
- See @ref overview_printersettings "Printer settings" for functions to set and
- get PostScript printing settings.
- This constructor and the global printer settings are now deprecated;
- use the wxPrintData constructor instead.
+
+ Use the wxDC::Ok() member to test whether the constructor was
+ successful in creating a usable device context.
+
+ See wxPrintData for various functions to set and get PostScript
+ printing settings.
+
+ @deprecated This constructor is deprecated.
*/
- wxPostScriptDC(const wxPrintData& printData);
wxPostScriptDC(const wxString& output,
bool interactive = true,
wxWindow* parent);
- //@}
/**
- Return resolution used in PostScript output. See
- SetResolution().
+ Return resolution used in PostScript output.
+
+ @see SetResolution()
*/
static int GetResolution();
@class wxScreenDC
@wxheader{dcscreen.h}
- A wxScreenDC can be used to paint on the screen.
- This should normally be constructed as a temporary stack object; don't store
- a wxScreenDC object.
+ A wxScreenDC can be used to paint on the screen. This should normally be
+ constructed as a temporary stack object; don't store a wxScreenDC object.
@library{wxcore}
@category{dc}
/**
Use this in conjunction with StartDrawingOnTop().
- This function destroys the temporary window created to implement on-top drawing
- (X only).
+
+ This function destroys the temporary window created to implement on-top
+ drawing (X only).
*/
bool EndDrawingOnTop();
- //@{
/**
- Use this in conjunction with EndDrawingOnTop() to
- ensure that drawing to the screen occurs on top of existing windows. Without
- this,
- some window systems (such as X) only allow drawing to take place underneath
+ Use this in conjunction with EndDrawingOnTop() to ensure that drawing
+ to the screen occurs on top of existing windows. Without this, some
+ window systems (such as X) only allow drawing to take place underneath
other windows.
- By using the first form of this function, an application is specifying that
- the area that will be drawn on coincides with the given window.
- By using the second form, an application can specify an area of the screen
- which is to be drawn on. If @NULL is passed, the whole screen is available.
- It is recommended that an area of the screen is specified because with large
- regions,
- flickering effects are noticeable when destroying the temporary transparent
- window used
- to implement this feature.
- You might use this pair of functions when implementing a drag feature, for
- example
- as in the wxSplitterWindow implementation.
+
+ This version of StartDrawingOnTop() is used to specify that the area
+ that will be drawn on coincides with the given window. It is
+ recommended that an area of the screen is specified with
+ StartDrawingOnTop(wxRect*) because with large regions, flickering
+ effects are noticeable when destroying the temporary transparent window
+ used to implement this feature.
+
+ You might use this function when implementing a drag feature, for
+ example as in the wxSplitterWindow implementation.
@remarks This function is probably obsolete since the X implementations
- allow drawing directly on the screen now. However, the
- fact that this function allows the screen to be
- refreshed afterwards, may be useful to some
- applications.
+ allow drawing directly on the screen now. However, the fact
+ that this function allows the screen to be refreshed
+ afterwards, may be useful to some applications.
*/
bool StartDrawingOnTop(wxWindow* window);
+ /**
+ Use this in conjunction with EndDrawingOnTop() to ensure that drawing
+ to the screen occurs on top of existing windows. Without this, some
+ window systems (such as X) only allow drawing to take place underneath
+ other windows.
+
+ This version of StartDrawingOnTop() is used to specify an area of the
+ screen which is to be drawn on. If @NULL is passed, the whole screen is
+ available. It is recommended that an area of the screen is specified
+ with this function rather than with StartDrawingOnTop(wxWindow*),
+ because with large regions, flickering effects are noticeable when
+ destroying the temporary transparent window used to implement this
+ feature.
+
+ You might use this function when implementing a drag feature, for
+ example as in the wxSplitterWindow implementation.
+
+ @remarks This function is probably obsolete since the X implementations
+ allow drawing directly on the screen now. However, the fact
+ that this function allows the screen to be refreshed
+ afterwards, may be useful to some applications.
+ */
bool StartDrawingOnTop(wxRect* rect = NULL);
- //@}
};
@class wxSVGFileDC
@wxheader{dcsvg.h}
- A wxSVGFileDC is a @e device context onto which graphics and text can be drawn,
- and the output
- produced as a vector file, in the SVG format
- (see W3C specifications).
- This format can be read by a range of programs, including a Netscape plugin
- (Adobe), full details
- in the SVG Implementation and Resource Directory.
- Vector formats may often be smaller than raster formats.
+ A wxSVGFileDC is a device context onto which graphics and text can be
+ drawn, and the output produced as a vector file, in SVG format (see the W3C
+ SVG Specifications <http://www.w3.org/TR/2001/REC-SVG-20010904/>). This
+ format can be read by a range of programs, including a Netscape plugin
+ (Adobe), full details are given in the SVG Implementation and Resource
+ Directory <http://www.svgi.org/>. Vector formats may often be smaller than
+ raster formats.
The intention behind wxSVGFileDC is that it can be used to produce a file
- corresponding
- to the screen display context, wxSVGFileDC, by passing the wxSVGFileDC as a
- parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC is a write-only class.
+ corresponding to the screen display context, wxSVGFileDC, by passing the
+ wxSVGFileDC as a parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC
+ is a write-only class.
- As the wxSVGFileDC is a vector format, raster operations like GetPixel are
- unlikely to be supported.
- However, the SVG specification allows for PNG format raster files to be
- embedded in the SVG, and so
- bitmaps, icons and blit operations into the wxSVGFileDC are supported.
+ As the wxSVGFileDC is a vector format, raster operations like GetPixel()
+ are unlikely to be supported. However, the SVG specification allows for PNG
+ format raster files to be embedded in the SVG, and so bitmaps, icons and
+ blit operations in wxSVGFileDC are supported.
- A more substantial SVG library (for reading and writing) is available at the
- wxArt2D website.
+ A more substantial SVG library (for reading and writing) is available at
+ the wxArt2D website <http://wxart2d.sourceforge.net/>.
@library{wxcore}
- @category{FIXME}
-
- @see @b Members
+ @category{dc}
*/
class wxSVGFileDC : public wxDC
{
wxARCH_64,
wxARCH_MAX
-}
+};
/**
wxENDIAN_PDP, //!< 3412
wxENDIAN_MAX
-}
+};
/**
projects / wxWidgets.git / commitdiff
