← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/dcbuffer.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

Lines of Context:
interface/wx/dcbuffer.h
 
1
/////////////////////////////////////////////////////////////////////////////
 
2
// Name:        dcbuffer.h
 
3
// Purpose:     interface of wxBufferedDC
 
4
// Author:      wxWidgets team
 
5
// RCS-ID:      $Id: dcbuffer.h 69135 2011-09-18 04:38:01Z RD $
 
6
// Licence:     wxWindows licence
 
7
/////////////////////////////////////////////////////////////////////////////
 
8
 
 
9
// Assumes the buffer bitmap covers the entire scrolled window,
 
10
// and prepares the window DC accordingly
 
11
#define wxBUFFER_VIRTUAL_AREA       0x01
 
12
 
 
13
// Assumes the buffer bitmap only covers the client area;
 
14
// does not prepare the window DC
 
15
#define wxBUFFER_CLIENT_AREA        0x02
 
16
 
 
17
// Set when not using specific buffer bitmap. Note that this
 
18
// is private style and not returned by GetStyle.
 
19
#define wxBUFFER_USES_SHARED_BUFFER 0x04
 
20
 
 
21
 
 
22
/**
 
23
    @class wxBufferedDC
 
24
 
 
25
    This class provides a simple way to avoid flicker: when drawing on it,
 
26
    everything is in fact first drawn on an in-memory buffer (a wxBitmap) and
 
27
    then copied to the screen, using the associated wxDC, only once, when this
 
28
    object is destroyed. wxBufferedDC itself is typically associated with
 
29
    wxClientDC, if you want to use it in your @c EVT_PAINT handler, you should
 
30
    look at wxBufferedPaintDC instead.
 
31
 
 
32
    When used like this, a valid @e DC must be specified in the constructor
 
33
    while the @e buffer bitmap doesn't have to be explicitly provided, by
 
34
    default this class will allocate the bitmap of required size itself.
 
35
    However using a dedicated bitmap can speed up the redrawing process by
 
36
    eliminating the repeated creation and destruction of a possibly big bitmap.
 
37
    Otherwise, wxBufferedDC can be used in the same way as any other device
 
38
    context.
 
39
 
 
40
    There is another possible use for wxBufferedDC is to use it to maintain a
 
41
    backing store for the window contents. In this case, the associated @e DC
 
42
    may be @NULL but a valid backing store bitmap should be specified.
 
43
 
 
44
    Finally, please note that GTK+ 2.0 as well as OS X provide double buffering
 
45
    themselves natively. You can either use wxWindow::IsDoubleBuffered() to
 
46
    determine whether you need to use buffering or not, or use
 
47
    wxAutoBufferedPaintDC to avoid needless double buffering on the systems
 
48
    which already do it automatically.
 
49
 
 
50
    @library{wxcore}
 
51
    @category{dc}
 
52
 
 
53
    @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC
 
54
*/
 
55
class wxBufferedDC : public wxMemoryDC
 
56
{
 
57
public:
 
58
    /**
 
59
        Default constructor. You must call one of the Init() methods later in
 
60
        order to use the device context.
 
61
    */
 
62
    wxBufferedDC();
 
63
 
 
64
    /**
 
65
        Creates a buffer for the provided @a dc. Init() must not be called when
 
66
        using this constructor.
 
67
 
 
68
        @param dc
 
69
            The underlying DC: everything drawn to this object will be flushed
 
70
            to this DC when this object is destroyed. You may pass @NULL in
 
71
            order to just initialize the buffer, and not flush it.
 
72
        @param area
 
73
            The size of the bitmap to be used for buffering (this bitmap is
 
74
            created internally when it is not given explicitly).
 
75
        @param style
 
76
            wxBUFFER_CLIENT_AREA to indicate that just the client area of the
 
77
            window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the
 
78
            buffer bitmap covers the virtual area.
 
79
    */
 
80
    wxBufferedDC(wxDC* dc, const wxSize& area,
 
81
                 int style = wxBUFFER_CLIENT_AREA);
 
82
 
 
83
    /**
 
84
        Creates a buffer for the provided dc. Init() must not be called when
 
85
        using this constructor.
 
86
 
 
87
        @param dc
 
88
            The underlying DC: everything drawn to this object will be flushed
 
89
            to this DC when this object is destroyed. You may pass @NULL in
 
90
            order to just initialize the buffer, and not flush it.
 
91
        @param buffer
 
92
            Explicitly provided bitmap to be used for buffering: this is the
 
93
            most efficient solution as the bitmap doesn't have to be recreated
 
94
            each time but it also requires more memory as the bitmap is never
 
95
            freed. The bitmap should have appropriate size, anything drawn
 
96
            outside of its bounds is clipped.
 
97
        @param style
 
98
            wxBUFFER_CLIENT_AREA to indicate that just the client area of the
 
99
            window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the
 
100
            buffer bitmap covers the virtual area.
 
101
    */
 
102
    wxBufferedDC(wxDC* dc, wxBitmap& buffer = wxNullBitmap,
 
103
                 int style = wxBUFFER_CLIENT_AREA);
 
104
 
 
105
    /**
 
106
        Copies everything drawn on the DC so far to the underlying DC
 
107
        associated with this object, if any.
 
108
    */
 
109
    virtual ~wxBufferedDC();
 
110
 
 
111
    //@{
 
112
    /**
 
113
        Initializes the object created using the default constructor. Please
 
114
        see the constructors for parameter details.
 
115
    */
 
116
    void Init(wxDC* dc, const wxSize& area,
 
117
              int style = wxBUFFER_CLIENT_AREA);
 
118
    void Init(wxDC* dc, wxBitmap& buffer = wxNullBitmap,
 
119
              int style = wxBUFFER_CLIENT_AREA);
 
120
    //@}
 
121
};
 
122
 
 
123
 
 
124
 
 
125
/**
 
126
    @class wxAutoBufferedPaintDC
 
127
 
 
128
    This wxDC derivative can be used inside of an @c EVT_PAINT() event handler
 
129
    to achieve double-buffered drawing. Just use this class instead of
 
130
    wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with
 
131
    wxBG_STYLE_PAINT somewhere in the class initialization code, and that's
 
132
    all you have to do to (mostly) avoid flicker.
 
133
 
 
134
    The difference between wxBufferedPaintDC and this class is that this class
 
135
    won't double-buffer on platforms which have native double-buffering
 
136
    already, avoiding any unnecessary buffering to avoid flicker.
 
137
 
 
138
    wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that
 
139
    have native double-buffering, otherwise, it is a typedef of
 
140
    wxBufferedPaintDC.
 
141
 
 
142
    @library{wxbase}
 
143
    @category{dc}
 
144
 
 
145
    @see wxDC, wxBufferedPaintDC, wxPaintDC
 
146
*/
 
147
class wxAutoBufferedPaintDC : public wxBufferedPaintDC
 
148
{
 
149
public:
 
150
    /**
 
151
        Constructor. Pass a pointer to the window on which you wish to paint.
 
152
    */
 
153
    wxAutoBufferedPaintDC(wxWindow* window);
 
154
};
 
155
 
 
156
 
 
157
 
 
158
/**
 
159
    @class wxBufferedPaintDC
 
160
 
 
161
    This is a subclass of wxBufferedDC which can be used inside of an
 
162
    @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use
 
163
    this class instead of wxPaintDC and make sure
 
164
    wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_PAINT somewhere
 
165
    in the class initialization code, and that's all you have to do to (mostly)
 
166
    avoid flicker. The only thing to watch out for is that if you are using
 
167
    this class together with wxScrolled, you probably do @b not want to call
 
168
    wxScrolled::PrepareDC() on it as it already does this internally for the
 
169
    real underlying wxPaintDC.
 
170
 
 
171
    @library{wxcore}
 
172
    @category{dc}
 
173
 
 
174
    @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC
 
175
*/
 
176
class wxBufferedPaintDC : public wxBufferedDC
 
177
{
 
178
public:
 
179
    //@{
 
180
    /**
 
181
        As with wxBufferedDC, you may either provide the bitmap to be used for
 
182
        buffering or let this object create one internally (in the latter case,
 
183
        the size of the client part of the window is used).
 
184
 
 
185
        Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that
 
186
        just the client area of the window is buffered, or
 
187
        wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the
 
188
        virtual area.
 
189
    */
 
190
    wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer,
 
191
                      int style = wxBUFFER_CLIENT_AREA);
 
192
    wxBufferedPaintDC(wxWindow* window,
 
193
                      int style = wxBUFFER_CLIENT_AREA);
 
194
    //@}
 
195
 
 
196
    /**
 
197
        Copies everything drawn on the DC so far to the window associated with
 
198
        this object, using a wxPaintDC.
 
199
    */
 
200
    virtual ~wxBufferedPaintDC();
 
201
};
 
202