From 3a7fb603c3ec7afbbf887e2c804085e21da99163 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Sat, 19 Apr 2008 08:12:58 +0000 Subject: [PATCH] More dc* interface headers reviewed. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53262 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/Doxyfile_inc | 2 +- docs/doxygen/mainpages/devtips.h | 9 ++-- interface/dcclient.h | 54 +++++++++---------- interface/dcmemory.h | 92 +++++++++++++++++++++----------- interface/dcmirror.h | 16 +++--- interface/dcprint.h | 52 ++++++++++-------- interface/dcps.h | 33 +++++++----- interface/dcscreen.h | 70 ++++++++++++++---------- interface/dcsvg.h | 38 ++++++------- interface/platinfo.h | 4 +- 10 files changed, 211 insertions(+), 159 deletions(-) diff --git a/docs/doxygen/Doxyfile_inc b/docs/doxygen/Doxyfile_inc index 0d3fca4234..5a35855af4 100644 --- a/docs/doxygen/Doxyfile_inc +++ b/docs/doxygen/Doxyfile_inc @@ -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="true" diff --git a/docs/doxygen/mainpages/devtips.h b/docs/doxygen/mainpages/devtips.h index 0ca7bea32f..3aa29be9ac 100644 --- a/docs/doxygen/mainpages/devtips.h +++ b/docs/doxygen/mainpages/devtips.h @@ -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 . +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. diff --git a/interface/dcclient.h b/interface/dcclient.h index b39198cdf5..5047ac053a 100644 --- a/interface/dcclient.h +++ b/interface/dcclient.h @@ -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 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} diff --git a/interface/dcmemory.h b/interface/dcmemory.h index 5b3d9b97db..e1e6a998eb 100644 --- a/interface/dcmemory.h +++ b/interface/dcmemory.h @@ -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). - - @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); }; diff --git a/interface/dcmirror.h b/interface/dcmirror.h index 24e77ba59e..4380e58a6b 100644 --- a/interface/dcmirror.h +++ b/interface/dcmirror.h @@ -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). */ diff --git a/interface/dcprint.h b/interface/dcprint.h index 075a943af5..db6c74f0eb 100644 --- a/interface/dcprint.h +++ b/interface/dcprint.h @@ -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(); }; diff --git a/interface/dcps.h b/interface/dcps.h index 27f2ec4b9d..34630fb92f 100644 --- a/interface/dcps.h +++ b/interface/dcps.h @@ -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(); diff --git a/interface/dcscreen.h b/interface/dcscreen.h index 17bc9cec98..80e4c9ec66 100644 --- a/interface/dcscreen.h +++ b/interface/dcscreen.h @@ -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); - //@} }; diff --git a/interface/dcsvg.h b/interface/dcsvg.h index ec95381002..a6c8c1a274 100644 --- a/interface/dcsvg.h +++ b/interface/dcsvg.h @@ -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 ). 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 . 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 . @library{wxcore} - @category{FIXME} - - @see @b Members + @category{dc} */ class wxSVGFileDC : public wxDC { diff --git a/interface/platinfo.h b/interface/platinfo.h index a1b0060ee9..71439b625d 100644 --- a/interface/platinfo.h +++ b/interface/platinfo.h @@ -90,7 +90,7 @@ enum wxArchitecture wxARCH_64, wxARCH_MAX -} +}; /** @@ -105,7 +105,7 @@ enum wxEndianness wxENDIAN_PDP, //!< 3412 wxENDIAN_MAX -} +}; /** -- 2.45.2