docs/doxygen/overviews/customwidgets.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        customwidgets.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_customwidgets Creating a custom widget
  12
  13 @li @ref overview_customwidgets_whenwhy
  14 @li @ref overview_customwidgets_how
  15
  16 <hr>
  17
  18
  19 @section overview_customwidgets_whenwhy When and why you should write your custom widget
  20
  21 Typically combining the existing @ref group_class_ctrl controls in wxDialogs and
  22 wxFrames is sufficient to fullfill any GUI design.
  23 Using the wxWidgets standard controls makes your GUI looks native on all ports
  24 and is obviously easier and faster.
  25
  26 However there are situations where you need to show some particular kind of data
  27 which is not suited to any existing control.
  28 In these cases rather than hacking an existing control for something it has not
  29 been coinceived for, it's better to write a new widget.
  30
  31
  32 @section overview_customwidgets_how How to write the custom widget
  33
  34 There are at least two very different ways to implement a new widget.
  35
  36 The first is to build it upon wxWidgets existing classes, thus deriving it from
  37 wxControl or wxWindow. In this way you'll get a @b generic widget.
  38 This method has the advantage that writing a single
  39 implementation works on all ports; the disadvantage is that it the widget will
  40 look the same on all platforms, and thus it may not integrate well with the
  41 native look and feel.
  42
  43 The second method is to build it directly upon the native toolkits of the platforms you
  44 want to support (e.g. GTK+, Carbon and GDI). In this way you'll get a @b native widget.
  45 This method in fact has the advantage of a native look and feel but requires different
  46 implementations and thus more work.
  47
  48 In both cases you'll want to better explore some hot topics like:
  49 - @ref overview_windowsizing
  50 - @ref overview_eventhandling_custom to implement your custom widget's events.
  51 You will probably need also to gain some familiarity with the wxWidgets sources,
  52 since you'll need to interface with some undocumented wxWidgets internal mechanisms.
  53
  54
  55 @subsection overview_customwidgets_how_generic Writing a generic widget
  56
  57 Generic widgets are typically derived from wxControl or wxWindow.
  58 They are easy to write. The typical "template" is as follows:
  59
  60 @code
  61
  62 enum MySpecialWidgetStyles
  63 {
  64     SWS_LOOK_CRAZY = 1,
  65     SWS_LOOK_SERIOUS = 2,
  66     SWS_SHOW_BUTTON = 4,
  67
  68     SWS_DEFAULT_STYLE = (SWS_SHOW_BUTTON|SWS_LOOK_SERIOUS)
  69 };
  70
  71 class MySpecialWidget : public wxControl
  72 {
  73 public:
  74     MySpecialWidget() { Init(); }
  75
  76     MySpecialWidget(wxWindow *parent,
  77                     wxWindowID winid,
  78                     const wxString& label,
  79                     const wxPoint& pos = wxDefaultPosition,
  80                     const wxSize& size = wxDefaultSize,
  81                     long style = SWS_DEFAULT_STYLE,
  82                     const wxValidator& val = wxDefaultValidator,
  83                     const wxString& name = "MySpecialWidget")
  84     {
  85         Init();
  86
  87         Create(parent, winid, label, pos, size, style, val, name);
  88     }
  89
  90     bool Create(wxWindow *parent,
  91                 wxWindowID winid,
  92                 const wxString& label,
  93                 const wxPoint& pos = wxDefaultPosition,
  94                 const wxSize& size = wxDefaultSize,
  95                 long style = SWS_DEFAULT_STYLE,
  96                 const wxValidator& val = wxDefaultValidator,
  97                 const wxString& name = wxCollapsiblePaneNameStr);
  98
  99     // accessors...
 100
 101 protected:
 102
 103     void Init() {
 104         // init widget's internals...
 105     }
 106
 107     virtual wxSize DoGetBestSize() const {
 108         // we need to calculate and return the best size of the widget...
 109     }
 110
 111     void OnPaint(wxPaintEvent&) {
 112         // draw the widget on a wxDC...
 113     }
 114
 115 private:
 116     DECLARE_DYNAMIC_CLASS(MySpecialWidget)
 117     DECLARE_EVENT_TABLE()
 118 };
 119 @endcode
 120
 121
 122
 123 @subsection overview_customwidgets_how_native Writing a native widget
 124
 125 Writing a native widget is typically more difficult as it requires you to
 126 know the APIs of the platforms you want to support.
 127 See @ref page_port_nativedocs for links to the documentation manuals of the
 128 various toolkits.
 129
 130 The organization used by wxWidgets consists in:
 131 - declaring the common interface of the control in a generic header, using
 132   the 'Base' postfix; e.g. MySpecialWidgetBase.
 133   See for example the wxWidgets' @c "wx/button.h" file.
 134
 135 - declaring the real widget class inheriting from the Base version in
 136   platform-specific headers; see for example the wxWidgets' @c "wx/gtk/button.h" file.
 137
 138 - separing the different implementations in different source files, putting
 139   all common stuff in a separate source.
 140   See for example the wxWidgets' @c "src/common/btncmn.cpp", @c "src/gtk/button.cpp"
 141   and @c "src/msw/button.cpp" files.
 142
 143 */
 144