docs/doxygen/overviews/dc.h

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