interface/wx/custombgwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/custombgwin.h
   3 // Purpose:     Documentation of wxCustomBackgroundWindow.
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-10-10
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     A helper class making it possible to use custom background for any window.
  13
  14     wxWindow itself only provides SetBackgroundColour() method taking a (solid)
  15     wxColour. This class extends it by allowing to use custom bitmap
  16     backgrounds with any window, provided that you inherit from it. Notice that
  17     the usual rule of not interfering with event handling or painting of native
  18     controls still applies, so you shouldn't try to use custom backgrounds with
  19     classes such as wxButton (even if this might work on some platforms, it's
  20     not guaranteed to work in general). But you can use this class in
  21     conjunction with wxWindow, wxPanel, wxFrame and other similar classes, e.g.
  22     the erase sample shows how to use it with wxScrolledWindow:
  23
  24     @code
  25         #include "wx/custombgwin.h"
  26
  27         class MyCanvas : public wxCustomBackgroundWindow<wxScrolledWindow>
  28         {
  29         public:
  30             MyCanvas(wxWindow* parent)
  31             {
  32                 // Notice that we must explicitly call base class Create()
  33                 // instead of using its ctor as wxCustomBackgroundWindow
  34                 // doesn't define any non-default ctors.
  35                 Create(parent, wxID_ANY);
  36
  37                 ...
  38
  39                 SetBackgroundBitmap(bitmap);
  40             }
  41         };
  42     @endcode
  43
  44     @category{miscwnd}
  45
  46     @since 2.9.3
  47  */
  48 template <class W>
  49 class wxCustomBackgroundWindow : public W
  50 {
  51 public:
  52     /// Trivial default constructor.
  53     wxCustomBackgroundWindow();
  54
  55     /**
  56         Set the background bitmap for this window.
  57
  58         If @a bmp is a valid bitmap, this bitmap will be tiled over the panel
  59         background and show through any of its transparent children. Passing an
  60         invalid bitmap reverts to the default background appearance.
  61
  62         Notice that you must not prevent the base class EVT_ERASE_BACKGROUND
  63         handler from running (i.e. not to handle this event yourself) for this
  64         to work.
  65     */
  66     void SetBackgroundBitmap(const wxBitmap& bmp);
  67 };