interface/dcmemory.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dcmemory.h
   3 // Purpose:     documentation for wxMemoryDC class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMemoryDC
  11     @wxheader{dcmemory.h}
  12
  13     A memory device context provides a means to draw graphics onto a bitmap. When
  14     drawing in to a mono-bitmap, using @c wxWHITE, @c wxWHITE_PEN and
  15     @c wxWHITE_BRUSH
  16     will draw the background colour (i.e. 0) whereas all other colours will draw the
  17     foreground colour (i.e. 1).
  18
  19     @library{wxcore}
  20     @category{dc}
  21
  22     @seealso
  23     wxBitmap, wxDC
  24 */
  25 class wxMemoryDC : public wxDC
  26 {
  27 public:
  28     //@{
  29     /**
  30         Constructs a new memory device context and calls SelectObject()
  31         with the given bitmap.
  32         Use the wxDC::IsOk member to test whether the constructor was successful
  33         in creating a usable device context.
  34     */
  35     wxMemoryDC();
  36     wxMemoryDC(wxBitmap& bitmap);
  37     //@}
  38
  39     /**
  40         Works exactly like SelectObjectAsSource() but
  41         this is the function you should use when you select a bitmap because you want
  42         to modify
  43         it, e.g. drawing on this DC.
  44
  45         Using SelectObjectAsSource() when modifying
  46         the bitmap may incurr some problems related to wxBitmap being a reference
  47         counted object
  48         (see @ref overview_trefcount "reference counting overview").
  49
  50         Also, before using the updated bitmap data, make sure to select it out of
  51         context first
  52         (for example by selecting wxNullBitmap into the device context).
  53
  54         @sa wxDC::DrawBitmap
  55     */
  56     void SelectObject(wxBitmap& bitmap);
  57
  58     /**
  59         Selects the given bitmap into the device context, to use as the memory
  60         bitmap. Selecting the bitmap into a memory DC allows you to draw into
  61         the DC (and therefore the bitmap) and also to use wxDC::Blit to copy
  62         the bitmap to a window. For this purpose, you may find wxDC::DrawIcon
  63         easier to use instead.
  64
  65         If the argument is wxNullBitmap (or some other uninitialised wxBitmap) the
  66         current bitmap is
  67         selected out of the device context, and the original bitmap restored, allowing
  68         the current bitmap to
  69         be destroyed safely.
  70     */
  71     void SelectObjectAsSource(const wxBitmap& bitmap);
  72 };