docs/doxygen/overviews/dc.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dc.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9
  10 @page overview_dc Device Contexts
  11
  12 A wxDC is a @e device context onto which graphics and text can be drawn.
  13 The device context is intended to represent a number of output devices in a
  14 generic way, with the same API being used throughout.
  15
  16 Some device contexts are created temporarily in order to draw on a window.
  17 This is @true of wxScreenDC, wxClientDC, wxPaintDC, and wxWindowDC.
  18 The following describes the differences between these device contexts and
  19 when you should use them.
  20
  21 @li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
  22 @li @b wxClientDC. Use this to paint on the client area of window (the part without
  23     borders and other decorations), but do not use it from within an wxPaintEvent.
  24 @li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
  25     within a wxPaintEvent.
  26 @li @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
  27     This may not be available on non-Windows platforms.
  28
  29 To use a client, paint or window device context, create an object on the stack with
  30 the window as argument, for example:
  31
  32 @code
  33 void MyWindow::OnMyCmd(wxCommandEvent& event)
  34 {
  35     wxClientDC dc(window);
  36     DrawMyPicture(dc);
  37 }
  38 @endcode
  39
  40 Try to write code so it is parameterised by wxDC - if you do this, the same piece of code may
  41 write to a number of different devices, by passing a different device context. This doesn't
  42 work for everything (for example not all device contexts support bitmap drawing) but
  43 will work most of the time.
  44
  45 @see @ref group_class_dc
  46
  47 */