]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/doxygen/overviews/customwidgets.h
Implement hatched/stippled pens/brushes in wxGraphicsContext for Cairo.
[wxWidgets.git] / docs / doxygen / overviews / customwidgets.h
... / ...
CommitLineData
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@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
21Typically combining the existing @ref group_class_ctrl controls in wxDialogs and
22wxFrames is sufficient to fullfill any GUI design.
23Using the wxWidgets standard controls makes your GUI looks native on all ports
24and is obviously easier and faster.
25
26However there are situations where you need to show some particular kind of data
27which is not suited to any existing control.
28In these cases rather than hacking an existing control for something it has not
29been conceived for, it's better to write a new widget.
30
31
32@section overview_customwidgets_how How to write the custom widget
33
34There are at least two very different ways to implement a new widget.
35
36The first is to build it upon wxWidgets existing classes, thus deriving it from
37wxControl or wxWindow. In this way you'll get a @b generic widget.
38This method has the advantage that writing a single
39implementation works on all ports; the disadvantage is that it the widget will
40look the same on all platforms, and thus it may not integrate well with the
41native look and feel.
42
43The second method is to build it directly upon the native toolkits of the platforms you
44want to support (e.g. GTK+, Carbon and GDI). In this way you'll get a @b native widget.
45This method in fact has the advantage of a native look and feel but requires different
46implementations and thus more work.
47
48In both cases you'll want to better explore some hot topics like:
49- @ref overview_windowsizing
50- @ref overview_events_custom to implement your custom widget's events.
51You will probably need also to gain some familiarity with the wxWidgets sources,
52since you'll need to interface with some undocumented wxWidgets internal mechanisms.
53
54
55@subsection overview_customwidgets_how_generic Writing a generic widget
56
57Generic widgets are typically derived from wxControl or wxWindow.
58They are easy to write. The typical "template" is as follows:
59
60@code
61
62enum 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
71class MySpecialWidget : public wxControl
72{
73public:
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
101protected:
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
115private:
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
125Writing a native widget is typically more difficult as it requires you to
126know the APIs of the platforms you want to support.
127See @ref page_port_nativedocs for links to the documentation manuals of the
128various toolkits.
129
130The 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- separating 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