interface/wx/panel.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        panel.h
   3 // Purpose:     interface of wxPanel
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPanel
  11
  12     A panel is a window on which controls are placed. It is usually placed within
  13     a frame. Its main feature over its parent class wxWindow is code for handling
  14     child windows and TAB traversal. Since wxWidgets 2.9, there is support both
  15     for TAB traversal implemented by wxWidgets itself as well as native TAB
  16     traversal (such as for GTK 2.0).
  17
  18     @note Tab traversal is implemented through an otherwise undocumented
  19           intermediate wxControlContainer class from which any class can derive
  20           in addition to the normal wxWindow base class. Please see @c wx/containr.h
  21           and @c wx/panel.h to find out how this is achieved.
  22
  23     @note if not all characters are being intercepted by your OnKeyDown or
  24           OnChar handler, it may be because you are using the @c wxTAB_TRAVERSAL style,
  25           which grabs some keypresses for use by child controls.
  26
  27     @remarks By default, a panel has the same colouring as a dialog.
  28
  29     @beginEventEmissionTable{wxNavigationKeyEvent}
  30     @event{EVT_NAVIGATION_KEY(func)}
  31         Process a navigation key event.
  32     @endEventTable
  33
  34     @library{wxbase}
  35     @category{miscwnd}
  36
  37     @see wxDialog
  38 */
  39 class wxPanel : public wxWindow
  40 {
  41 public:
  42
  43     /**
  44         Default constructor.
  45     */
  46     wxPanel();
  47
  48     /**
  49         Constructor.
  50
  51         @param parent
  52             The parent window.
  53         @param id
  54             An identifier for the panel. @c wxID_ANY is taken to mean a default.
  55         @param pos
  56             The panel position. The value ::wxDefaultPosition indicates a default position,
  57             chosen by either the windowing system or wxWidgets, depending on platform.
  58         @param size
  59             The panel size. The value ::wxDefaultSize indicates a default size, chosen by
  60             either the windowing system or wxWidgets, depending on platform.
  61         @param style
  62             The window style. See wxPanel.
  63         @param name
  64             Window name.
  65
  66         @see Create()
  67     */
  68     wxPanel(wxWindow* parent, wxWindowID id = wxID_ANY,
  69             const wxPoint& pos = wxDefaultPosition,
  70             const wxSize& size = wxDefaultSize,
  71             long style = wxTAB_TRAVERSAL,
  72             const wxString& name = wxPanelNameStr);
  73
  74     /**
  75         Destructor. Deletes any child windows before deleting the physical window.
  76     */
  77     virtual ~wxPanel();
  78
  79     /**
  80         This method is overridden from wxWindow::AcceptsFocus()
  81         and returns @true only if there is no child window in the panel which
  82         can accept the focus. This is reevaluated each time a child
  83         window is added or removed from the panel.
  84     */
  85     bool AcceptsFocus() const;
  86
  87     /**
  88         Used for two-step panel construction. See wxPanel() for details.
  89     */
  90     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  91                 const wxPoint& pos = wxDefaultPosition,
  92                 const wxSize& size = wxDefaultSize,
  93                 long style = wxTAB_TRAVERSAL,
  94                 const wxString& name = wxPanelNameStr);
  95
  96     /**
  97         Sends a wxInitDialogEvent, which in turn transfers data to the dialog via
  98         validators.
  99
 100         @see wxInitDialogEvent
 101     */
 102     virtual void InitDialog();
 103
 104     /**
 105         See wxWindow::SetAutoLayout(): when auto layout is on, this function gets
 106         called automatically when the window is resized.
 107     */
 108     virtual bool Layout();
 109
 110     /**
 111         The default handler for @c wxEVT_SYS_COLOUR_CHANGED.
 112
 113         @param event
 114             The colour change event.
 115
 116         @remarks Changes the panel's colour to conform to the current settings
 117                  (Windows only). Add an event table entry for your panel
 118                  class if you wish the behaviour to be different (such
 119                  as keeping a user-defined background colour). If you do
 120                  override this function, call wxEvent::Skip() to propagate
 121                  the notification to child windows and controls.
 122
 123         @see wxSysColourChangedEvent
 124     */
 125     void OnSysColourChanged(wxSysColourChangedEvent& event);
 126
 127     /**
 128         Set the background bitmap for this panel.
 129
 130         If @a bmp is a valid bitmap, this bitmap will be tiled over the panel
 131         background and show through any of its transparent children. Passing an
 132         invalid bitmap reverts to the default background appearance.
 133
 134         Notice that you must not prevent the base class EVT_ERASE_BACKGROUND
 135         handler from running (i.e. not to handle this event yourself) for this
 136         to work.
 137
 138         @since 2.9.2
 139     */
 140     void SetBackgroundBitmap(const wxBitmap& bmp);
 141
 142     /**
 143         Overrides wxWindow::SetFocus().
 144
 145         This method uses the (undocumented) mix-in class wxControlContainer which manages
 146         the focus and TAB logic for controls which usually have child controls.
 147
 148         In practice, if you call this method and the control has at least
 149         one child window, the focus will be given to the child window.
 150
 151         @see wxFocusEvent, wxWindow::SetFocus()
 152     */
 153     virtual void SetFocus();
 154
 155     /**
 156         In contrast to SetFocus() (see above) this will set the focus to the panel
 157         even if there are child windows in the panel. This is only rarely needed.
 158     */
 159     void SetFocusIgnoringChildren();
 160 };
 161