X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c4f71cc3d63fb7bdfbd6cec3e39c8a8679f3e60..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/dcbuffer.h?ds=sidebyside diff --git a/interface/dcbuffer.h b/interface/dcbuffer.h index 5d1dcf5956..569ccdba03 100644 --- a/interface/dcbuffer.h +++ b/interface/dcbuffer.h @@ -11,29 +11,29 @@ @wxheader{dcbuffer.h} This class provides a simple way to avoid flicker: when drawing on it, - everything is in fact first drawn on an in-memory buffer (a - wxBitmap) and then copied to the screen, using the - associated wxDC, only once, when this object is destroyed. wxBufferedDC itself - is typically associated with wxClientDC, if you want to - use it in your @c EVT_PAINT handler, you should look at - wxBufferedPaintDC instead. - - When used like this, a valid @e dc must be specified in the constructor + everything is in fact first drawn on an in-memory buffer (a wxBitmap) and + then copied to the screen, using the associated wxDC, only once, when this + object is destroyed. wxBufferedDC itself is typically associated with + wxClientDC, if you want to use it in your @c EVT_PAINT handler, you should + look at wxBufferedPaintDC instead. + + When used like this, a valid @e DC must be specified in the constructor while the @e buffer bitmap doesn't have to be explicitly provided, by - default this class will allocate the bitmap of required size itself. However - using a dedicated bitmap can speed up the redrawing process by eliminating the - repeated creation and destruction of a possibly big bitmap. Otherwise, - wxBufferedDC can be used in the same way as any other device context. + default this class will allocate the bitmap of required size itself. + However using a dedicated bitmap can speed up the redrawing process by + eliminating the repeated creation and destruction of a possibly big bitmap. + Otherwise, wxBufferedDC can be used in the same way as any other device + context. There is another possible use for wxBufferedDC is to use it to maintain a - backing store for the window contents. In this case, the associated @e dc + backing store for the window contents. In this case, the associated @e DC may be @NULL but a valid backing store bitmap should be specified. Finally, please note that GTK+ 2.0 as well as OS X provide double buffering - themselves natively. You can either use wxWindow::IsDoubleBuffered - to determine whether you need to use buffering or not, or use - wxAutoBufferedPaintDC to avoid needless double - buffering on the systems which already do it automatically. + themselves natively. You can either use wxWindow::IsDoubleBuffered() to + determine whether you need to use buffering or not, or use + wxAutoBufferedPaintDC to avoid needless double buffering on the systems + which already do it automatically. @library{wxcore} @category{dc} @@ -43,36 +43,35 @@ class wxBufferedDC : public wxMemoryDC { public: + /** + Default constructor. You must call one of the Init() methods later in + order to use the device context. + */ + wxBufferedDC(); + //@{ /** - If you use the first, default, constructor, you must call one of the - Init() methods later in order to use the object. - The other constructors initialize the object immediately and @c Init() - must not be called after using them. + Creates a buffer for the provided @dc. Init() must not be called when + using this constructor. @param dc - The underlying DC: everything drawn to this object will be - flushed to this DC when this object is destroyed. You may pass @NULL - in order to just initialize the buffer, and not flush it. + The underlying DC: everything drawn to this object will be flushed + to this DC when this object is destroyed. You may pass @NULL in + order to just initialize the buffer, and not flush it. @param area The size of the bitmap to be used for buffering (this bitmap is created internally when it is not given explicitly). @param buffer - Explicitly provided bitmap to be used for buffering: this is - the most efficient solution as the bitmap doesn't have to be recreated each - time but it also requires more memory as the bitmap is never freed. The - bitmap - should have appropriate size, anything drawn outside of its bounds is - clipped. + Explicitly provided bitmap to be used for buffering: this is the + most efficient solution as the bitmap doesn't have to be recreated + each time but it also requires more memory as the bitmap is never + freed. The bitmap should have appropriate size, anything drawn + outside of its bounds is clipped. @param style - wxBUFFER_CLIENT_AREA to indicate that just the client area of - the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the - buffer bitmap - covers the virtual area (in which case PrepareDC is automatically called - for the actual window - device context). + wxBUFFER_CLIENT_AREA to indicate that just the client area of the + window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the + buffer bitmap covers the virtual area. */ - wxBufferedDC(); wxBufferedDC(wxDC* dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA); wxBufferedDC(wxDC* dc, wxBitmap& buffer, @@ -80,15 +79,15 @@ public: //@} /** - Copies everything drawn on the DC so far to the underlying DC associated with - this object, if any. + Copies everything drawn on the DC so far to the underlying DC + associated with this object, if any. */ - + ~wxBufferedDC(); //@{ /** - These functions initialize the object created using the default constructor. - Please see @ref ctor() "constructors documentation" for details. + Initializes the object created using the default constructor. Please + see the constructors for parameter details. */ void Init(wxDC* dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA); @@ -103,24 +102,24 @@ public: @class wxAutoBufferedPaintDC @wxheader{dcbuffer.h} - This wxDC derivative can be used inside of an @c OnPaint() event handler to - achieve - double-buffered drawing. Just create an object of this class instead of - wxPaintDC - and make sure wxWindow::SetBackgroundStyle is called - with wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's - all you have - to do to (mostly) avoid flicker. + This wxDC derivative can be used inside of an @c EVT_PAINT() event handler + to achieve double-buffered drawing. Just use this class instead of + wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with + wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's + all you have to do to (mostly) avoid flicker. + + The difference between wxBufferedPaintDC and this class is that this class + won't double-buffer on platforms which have native double-buffering + already, avoiding any unneccessary buffering to avoid flicker. - The difference between wxBufferedPaintDC and this class, - is the lightweigthness - on platforms which have native double-buffering, - wxAutoBufferedPaintDC is simply - a typedef of wxPaintDC. Otherwise, it is a typedef of wxBufferedPaintDC. + wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that + have native double-buffering, otherwise, it is a typedef of + wxBufferedPaintDC. @library{wxbase} @category{dc} - @see wxDC, wxBufferedPaintDC + @see wxDC, wxBufferedPaintDC, wxPaintDC */ class wxAutoBufferedPaintDC : public wxBufferedPaintDC { @@ -137,38 +136,34 @@ public: @class wxBufferedPaintDC @wxheader{dcbuffer.h} - This is a subclass of wxBufferedDC which can be used - inside of an @c OnPaint() event handler. Just create an object of this class - instead - of wxPaintDC and make sure wxWindow::SetBackgroundStyle - is called with wxBG_STYLE_CUSTOM somewhere in the class initialization code, - and that's all - you have to do to (mostly) avoid flicker. The only thing to watch out for is - that if you are - using this class together with wxScrolledWindow, you probably - do @b not want to call wxScrolledWindow::PrepareDC on it as it - already does this internally for the real underlying wxPaintDC. + This is a subclass of wxBufferedDC which can be used inside of an + @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use + this class instead of wxPaintDC and make sure + wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_CUSTOM somewhere + in the class initialization code, and that's all you have to do to (mostly) + avoid flicker. The only thing to watch out for is that if you are using + this class together with wxScrolled, you probably do @b not want to call + wxScrolled::PrepareDC() on it as it already does this internally for the + real underlying wxPaintDC. @library{wxcore} @category{dc} - @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC + @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC */ class wxBufferedPaintDC : public wxBufferedDC { public: //@{ /** - As with @ref wxBufferedDC::ctor wxBufferedDC, you may either provide the - bitmap to be used for buffering or let this object create one internally (in - the latter case, the size of the client part of the window is used). - Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that just the - client area of - the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer - bitmap - covers the virtual area (in which case PrepareDC is automatically called for - the actual window - device context). + As with wxBufferedDC, you may either provide the bitmap to be used for + buffering or let this object create one internally (in the latter case, + the size of the client part of the window is used). + + Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that + just the client area of the window is buffered, or + wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the + virtual area. */ wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA); @@ -177,8 +172,9 @@ public: //@} /** - Copies everything drawn on the DC so far to the window associated with this - object, using a wxPaintDC. + Copies everything drawn on the DC so far to the window associated with + this object, using a wxPaintDC. */ + ~wxBufferedPaintDC(); };