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"
# 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>"

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
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.

54
interface/dcclient.h
View File

@@ -1,6 +1,6 @@
/////////////////////////////////////////////////////////////////////////////
// Name: dcclient.h
// Purpose: interface of wxPaintDC
// Purpose: interface of wxClientDC and wxPaintDC
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@@ -11,25 +11,25 @@
@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
{
@@ -47,14 +47,15 @@ public:
@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}
@@ -77,17 +78,14 @@ public:
@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 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
wxClientDC object.
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}

90
interface/dcmemory.h
View File

@@ -10,11 +10,35 @@
@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}
@@ -24,45 +48,51 @@
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).
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.
@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);
/**
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);
};

16
interface/dcmirror.h
View File

@@ -11,12 +11,12 @@
@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}
@@ -25,8 +25,10 @@ class wxMirrorDC : public wxDC
{
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).
*/

52
interface/dcprint.h
View File

@@ -10,44 +10,50 @@
@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();
};

33
interface/dcps.h
View File

@@ -10,9 +10,9 @@
@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}
@@ -20,27 +20,32 @@
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();

70
interface/dcscreen.h
View File

@@ -10,9 +10,8 @@
@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}
@@ -29,39 +28,56 @@ public:
/**
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);
//@}
};

38
interface/dcsvg.h
View File

@@ -10,33 +10,29 @@
@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
{

4
interface/platinfo.h
View File

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