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