Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

More dc* interface headers reviewed.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53262 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-04-19 08:12:58 +00:00
parent efdb961d8f
commit 3a7fb603c3
10 changed files with 210 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/doxygen/Doxyfile_inc
View File

@@ -102,7 +102,7 @@ ALIASES += header{1}="Include file:\n \verbatim #include <\1> \endverbatim"
ALIASES += wxheader{1}="\headerfile \1 wx/\1" ALIASES += wxheader{1}="\headerfile \1 wx/\1"
# the following alias avoids to repeat lots of times the same statement: # 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 # some formatting aliases
ALIASES += true="<span class='literal'>true</span>" ALIASES += true="<span class='literal'>true</span>"

9
docs/doxygen/mainpages/devtips.h
View File

@@ -152,11 +152,10 @@ For details on using makefiles, configure, and project files, please see
@c "docs/xxx/install.txt" in your distribution, where @c "xxx" is the platform @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. of interest, such as @c msw, @c gtk, @c x11, @c mac.
All wxWidgets makefiles are generated using All wxWidgets makefiles are generated using Bakefile <http://www.bakefile.org/>.
@link http://www.bakefile.org Bakefile @endlink. wxWidgets also provides (in wxWidgets also provides (in the @c "build/bakefiles/wxpresets" folder) the
the @c "build/bakefiles/wxpresets" folder) the wxWidgets bakefile presets. wxWidgets bakefile presets. These files allow you to create bakefiles for your
These files allow you to create bakefiles for your own wxWidgets-based own wxWidgets-based applications very easily.
applications very easily.

54
interface/dcclient.h
View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: dcclient.h // Name: dcclient.h
// Purpose: interface of wxPaintDC // Purpose: interface of wxClientDC and wxPaintDC
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -11,25 +11,25 @@
@wxheader{dcclient.h} @wxheader{dcclient.h}
A wxPaintDC must be constructed if an application wishes to paint on the A wxPaintDC must be constructed if an application wishes to paint on the
client area of a window from within an @b OnPaint event. client area of a window from within an EVT_PAINT() event handler. This
This should normally be constructed as a temporary stack object; don't store should normally be constructed as a temporary stack object; don't store a
a wxPaintDC object. If you have an OnPaint handler, you @e must create a wxPaintDC object. If you have an EVT_PAINT() handler, you @e must create a
wxPaintDC wxPaintDC object within it even if you don't actually use it.
object within it even if you don't actually use it.
Using wxPaintDC within OnPaint is important because it automatically Using wxPaintDC within your EVT_PAINT() handler is important because it
sets the clipping area to the damaged area of the window. Attempts to draw automatically sets the clipping area to the damaged area of the window.
outside this area do not appear. 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 To draw on the whole window including decorations, construct a wxWindowDC
(Windows only). object (Windows only).
@library{wxcore} @library{wxcore}
@category{dc} @category{dc}
@see wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC @see wxDC, wxClientDC, wxMemoryDC, wxWindowDC, wxScreenDC
*/ */
class wxPaintDC : public wxWindowDC class wxPaintDC : public wxWindowDC
{ {
@@ -47,14 +47,15 @@ public:
@wxheader{dcclient.h} @wxheader{dcclient.h}
A wxClientDC must be constructed if an application wishes to paint on the A wxClientDC must be constructed if an application wishes to paint on the
client area of a window from outside an @b OnPaint event. client area of a window from outside an EVT_PAINT() handler. This should
This should normally be constructed as a temporary stack object; don't store normally be constructed as a temporary stack object; don't store a
a wxClientDC object. 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 To draw on the whole window including decorations, construct a wxWindowDC
(Windows only). object (Windows only).
@library{wxcore} @library{wxcore}
@category{dc} @category{dc}
@@ -77,17 +78,14 @@ public:
@wxheader{dcclient.h} @wxheader{dcclient.h}
A wxWindowDC must be constructed if an application wishes to paint on the A wxWindowDC must be constructed if an application wishes to paint on the
whole area of a window (client and decorations). whole area of a window (client and decorations). This should normally be
This should normally be constructed as a temporary stack object; don't store constructed as a temporary stack object; don't store a wxWindowDC object.
a wxWindowDC object.
To draw on a window from inside @b OnPaint, construct a wxPaintDC object. To draw on a window from inside an EVT_PAINT() handler, construct a
wxPaintDC object instead.
To draw on the client area of a window from outside @b OnPaint, construct a To draw on the client area of a window from outside an EVT_PAINT() handler,
wxClientDC object. construct a wxClientDC object.
To draw on the whole window including decorations, construct a wxWindowDC object
(Windows only).
@library{wxcore} @library{wxcore}
@category{dc} @category{dc}

90
interface/dcmemory.h
View File

@@ -10,11 +10,35 @@
@class wxMemoryDC @class wxMemoryDC
@wxheader{dcmemory.h} @wxheader{dcmemory.h}
A memory device context provides a means to draw graphics onto a bitmap. When A memory device context provides a means to draw graphics onto a bitmap.
drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and When drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and
@c wxWHITE_BRUSH @c wxWHITE_BRUSH will draw the background colour (i.e. 0) whereas all other
will draw the background colour (i.e. 0) whereas all other colours will draw the colours will draw the foreground colour (i.e. 1).
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} @library{wxcore}
@category{dc} @category{dc}
@@ -24,45 +48,51 @@
class wxMemoryDC : public wxDC class wxMemoryDC : public wxDC
{ {
public: public:
//@{
/** /**
Constructs a new memory device context and calls SelectObject() Constructs a new memory device context.
with the given bitmap.
Use the wxDC::IsOk member to test whether the constructor was successful Use the wxDC::Ok() member to test whether the constructor was
in creating a usable device context. successful in creating a usable device context. Don't forget to select
a bitmap into the DC before drawing on it.
*/ */
wxMemoryDC(); 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); wxMemoryDC(wxBitmap& bitmap);
//@}
/** /**
Works exactly like SelectObjectAsSource() but Works exactly like SelectObjectAsSource() but this is the function you
this is the function you should use when you select a bitmap because you want should use when you select a bitmap because you want to modify it, e.g.
to modify drawing on this DC.
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 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); void SelectObject(wxBitmap& bitmap);
/** /**
Selects the given bitmap into the device context, to use as the memory 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 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 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 bitmap to a window. For this purpose, you may find wxDC::DrawIcon()
easier to use instead. easier to use instead.
If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the
current bitmap is If the argument is wxNullBitmap (or some other uninitialised wxBitmap)
selected out of the device context, and the original bitmap restored, allowing the current bitmap is selected out of the device context, and the
the current bitmap to original bitmap restored, allowing the current bitmap to be destroyed
be destroyed safely. safely.
*/ */
void SelectObjectAsSource(const wxBitmap& bitmap); void SelectObjectAsSource(const wxBitmap& bitmap);
}; };

16
interface/dcmirror.h
View File

@@ -11,12 +11,12 @@
@wxheader{dcmirror.h} @wxheader{dcmirror.h}
wxMirrorDC is a simple wrapper class which is always associated with a real wxMirrorDC is a simple wrapper class which is always associated with a real
wxDC object and either forwards all of its operations to it wxDC object and either forwards all of its operations to it without changes
without changes (no mirroring takes place) or exchanges @e x and @e y (no mirroring takes place) or exchanges @e x and @e y coordinates which
coordinates which makes it possible to reuse the same code to draw a figure and makes it possible to reuse the same code to draw a figure and its mirror --
its mirror -- i.e. reflection related to the diagonal line x == y. 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} @library{wxcore}
@category{dc} @category{dc}
@@ -25,8 +25,10 @@ class wxMirrorDC : public wxDC
{ {
public: public:
/** /**
Creates a (maybe) mirrored DC associated with the real @e dc. Everything Creates a (maybe) mirrored DC associated with the real @a dc.
drawn on wxMirrorDC will appear (and maybe mirrored) on @e 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 @a mirror specifies if we do mirror (if it is @true) or not (if it is
@false). @false).
*/ */

52
interface/dcprint.h
View File

@@ -10,44 +10,50 @@
@class wxPrinterDC @class wxPrinterDC
@wxheader{dcprint.h} @wxheader{dcprint.h}
A printer device context is specific to MSW and Mac, and allows access to any A printer device context is specific to MSW and Mac, and allows access to
printer with a Windows or Macintosh driver. See wxDC for further any printer with a Windows or Macintosh driver. See wxDC for further
information on device contexts, and wxDC::GetSize for information on device contexts, and wxDC::GetSize() for advice on achieving
advice on achieving the correct scaling for the page. the correct scaling for the page.
@library{wxcore} @library{wxcore}
@category{printing} @category{printing}
@see @ref overview_printingoverview "Printing framework overview", wxDC @see @ref overview_printing, wxDC
*/ */
class wxPrinterDC : public wxDC class wxPrinterDC : public wxDC
{ {
public: public:
//@{
/** /**
Constructor. With empty strings for the first three arguments, the default Constructor. Pass a wxPrintData object with information necessary for
printer dialog is setting up a suitable printer device context. This is the recommended
displayed. @a device indicates the type of printer and @e output way to construct a wxPrinterDC. Make sure you specify a reference to a
is an optional file for printing to. The @a driver parameter is wxPrintData object, not a pointer - you may not even get a warning if
currently unused. Use the @e Ok member to test whether the you pass a pointer instead.
constructor was successful in creating a usable device context.
This constructor is deprecated and retained only for backward compatibility.
*/ */
wxPrinterDC(const wxPrintData& printData); 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, wxPrinterDC(const wxString& driver, const wxString& device,
const wxString& output, const wxString& output, const bool interactive = true,
const bool interactive = true,
int orientation = wxPORTRAIT); int orientation = wxPORTRAIT);
//@}
/** /**
Return the rectangle in device coordinates that corresponds to the full paper Return the rectangle in device coordinates that corresponds to the full
area, including the nonprinting regions of the paper. The point (0,0) in device paper area, including the nonprinting regions of the paper. The point
coordinates is the top left corner of the page rectangle, which is the printable (0,0) in device coordinates is the top left corner of the page
area on MSW and Mac. The coordinates of the top left corner of the paper rectangle, which is the printable area on MSW and Mac. The coordinates
rectangle will therefore have small negative values, while the bottom right of the top left corner of the paper rectangle will therefore have small
coordinates will be somewhat larger than the values returned by negative values, while the bottom right coordinates will be somewhat
wxDC::GetSize. larger than the values returned by wxDC::GetSize().
*/ */
wxRect wxPrinterDC::GetPaperRect(); wxRect wxPrinterDC::GetPaperRect();
}; };

33
interface/dcps.h
View File

@@ -10,9 +10,9 @@
@class wxPostScriptDC @class wxPostScriptDC
@wxheader{dcps.h} @wxheader{dcps.h}
This defines the wxWidgets Encapsulated PostScript device context, This defines the wxWidgets Encapsulated PostScript device context, which
which can write PostScript files on any platform. See wxDC for can write PostScript files on any platform. See wxDC for descriptions of
descriptions of the member functions. the member functions.
@library{wxbase} @library{wxbase}
@category{dc} @category{dc}
@@ -20,27 +20,32 @@
class wxPostScriptDC : public wxDC class wxPostScriptDC : public wxDC
{ {
public: 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 Constructor. @a output is an optional file for printing to, and if
@a interactive is @true a dialog box will be displayed for adjusting @a interactive is @true a dialog box will be displayed for adjusting
various parameters. @a parent is the parent of the printer dialog box. 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. Use the wxDC::Ok() member to test whether the constructor was
See @ref overview_printersettings "Printer settings" for functions to set and successful in creating a usable device context.
get PostScript printing settings.
This constructor and the global printer settings are now deprecated; See wxPrintData for various functions to set and get PostScript
use the wxPrintData constructor instead. printing settings.
@deprecated This constructor is deprecated.
*/ */
wxPostScriptDC(const wxPrintData& printData);
wxPostScriptDC(const wxString& output, wxPostScriptDC(const wxString& output,
bool interactive = true, bool interactive = true,
wxWindow* parent); wxWindow* parent);
//@}
/** /**
Return resolution used in PostScript output. See Return resolution used in PostScript output.
SetResolution().
@see SetResolution()
*/ */
static int GetResolution(); static int GetResolution();

70
interface/dcscreen.h
View File

@@ -10,9 +10,8 @@
@class wxScreenDC @class wxScreenDC
@wxheader{dcscreen.h} @wxheader{dcscreen.h}
A wxScreenDC can be used to paint on the screen. A wxScreenDC can be used to paint on the screen. This should normally be
This should normally be constructed as a temporary stack object; don't store constructed as a temporary stack object; don't store a wxScreenDC object.
a wxScreenDC object.
@library{wxcore} @library{wxcore}
@category{dc} @category{dc}
@@ -29,39 +28,56 @@ public:
/** /**
Use this in conjunction with StartDrawingOnTop(). 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(); bool EndDrawingOnTop();
//@{
/** /**
Use this in conjunction with EndDrawingOnTop() to Use this in conjunction with EndDrawingOnTop() to ensure that drawing
ensure that drawing to the screen occurs on top of existing windows. Without to the screen occurs on top of existing windows. Without this, some
this, window systems (such as X) only allow drawing to take place underneath
some window systems (such as X) only allow drawing to take place underneath
other windows. 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. This version of StartDrawingOnTop() is used to specify that the area
By using the second form, an application can specify an area of the screen that will be drawn on coincides with the given window. It is
which is to be drawn on. If @NULL is passed, the whole screen is available. recommended that an area of the screen is specified with
It is recommended that an area of the screen is specified because with large StartDrawingOnTop(wxRect*) because with large regions, flickering
regions, effects are noticeable when destroying the temporary transparent window
flickering effects are noticeable when destroying the temporary transparent used to implement this feature.
window used
to implement this feature. You might use this function when implementing a drag feature, for
You might use this pair of functions when implementing a drag feature, for example as in the wxSplitterWindow implementation.
example
as in the wxSplitterWindow implementation.
@remarks This function is probably obsolete since the X implementations @remarks This function is probably obsolete since the X implementations
allow drawing directly on the screen now. However, the allow drawing directly on the screen now. However, the fact
fact that this function allows the screen to be that this function allows the screen to be refreshed
refreshed afterwards, may be useful to some afterwards, may be useful to some applications.
applications.
*/ */
bool StartDrawingOnTop(wxWindow* window); 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); bool StartDrawingOnTop(wxRect* rect = NULL);
//@}
}; };

38
interface/dcsvg.h
View File

@@ -10,33 +10,29 @@
@class wxSVGFileDC @class wxSVGFileDC
@wxheader{dcsvg.h} @wxheader{dcsvg.h}
A wxSVGFileDC is a @e device context onto which graphics and text can be drawn, A wxSVGFileDC is a device context onto which graphics and text can be
and the output drawn, and the output produced as a vector file, in SVG format (see the W3C
produced as a vector file, in the SVG format SVG Specifications <http://www.w3.org/TR/2001/REC-SVG-20010904/>). This
(see W3C specifications). format can be read by a range of programs, including a Netscape plugin
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
(Adobe), full details Directory <http://www.svgi.org/>. Vector formats may often be smaller than
in the SVG Implementation and Resource Directory. raster formats.
Vector formats may often be smaller than raster formats.
The intention behind wxSVGFileDC is that it can be used to produce a file The intention behind wxSVGFileDC is that it can be used to produce a file
corresponding corresponding to the screen display context, wxSVGFileDC, by passing the
to the screen display context, wxSVGFileDC, by passing the wxSVGFileDC as a wxSVGFileDC as a parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC
parameter instead of a wxSVGFileDC. Thus the wxSVGFileDC is a write-only class. is a write-only class.
As the wxSVGFileDC is a vector format, raster operations like GetPixel are As the wxSVGFileDC is a vector format, raster operations like GetPixel()
unlikely to be supported. are unlikely to be supported. However, the SVG specification allows for PNG
However, the SVG specification allows for PNG format raster files to be format raster files to be embedded in the SVG, and so bitmaps, icons and
embedded in the SVG, and so blit operations in wxSVGFileDC are supported.
bitmaps, icons and blit operations into the wxSVGFileDC are supported.
A more substantial SVG library (for reading and writing) is available at the A more substantial SVG library (for reading and writing) is available at
wxArt2D website. the wxArt2D website <http://wxart2d.sourceforge.net/>.
@library{wxcore} @library{wxcore}
@category{FIXME} @category{dc}
@see @b Members
*/ */
class wxSVGFileDC : public wxDC class wxSVGFileDC : public wxDC
{ {

4
interface/platinfo.h
View File

@@ -90,7 +90,7 @@ enum wxArchitecture
wxARCH_64, wxARCH_64,
wxARCH_MAX wxARCH_MAX
} };
/** /**
@@ -105,7 +105,7 @@ enum wxEndianness
wxENDIAN_PDP, //!< 3412 wxENDIAN_PDP, //!< 3412
wxENDIAN_MAX wxENDIAN_MAX
} };
/** /**