From: Francesco Montorsi Date: Mon, 1 Dec 2008 17:46:20 +0000 (+0000) Subject: adding a new topic overview about writing custom widgets; currently there's no offici... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/64dd265011294daeb0746ef95645340971025b1f adding a new topic overview about writing custom widgets; currently there's no official guide... git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@57057 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index 61589e48a5..4fc700a58a 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -48,8 +48,10 @@ The following is a basic categorization of them: @li @subpage overview_exceptions @li @subpage overview_windowstyles @li @subpage overview_windowdeletion +@li @subpage overview_windowsizing @li @subpage overview_windowids @li @subpage overview_envvars +@li @subpage overview_customwidgets @section page_topics_nongui Non-GUI Classes @@ -80,7 +82,6 @@ The following is a basic categorization of them: @li @subpage overview_sizer @li @subpage overview_xrc @li @subpage overview_xrcformat -@li @subpage overview_windowsizing @li @subpage overview_scrolling @li @subpage overview_dialog @li @subpage overview_validator diff --git a/docs/doxygen/overviews/customwidgets.h b/docs/doxygen/overviews/customwidgets.h new file mode 100644 index 0000000000..471abd035f --- /dev/null +++ b/docs/doxygen/overviews/customwidgets.h @@ -0,0 +1,144 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: customwidgets.h +// Purpose: topic overview +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + +@page overview_customwidgets Creating a custom widget + +@li @ref overview_customwidgets_whenwhy +@li @ref overview_customwidgets_how + +
+ + +@section overview_customwidgets_whenwhy When and why you should write your custom widget + +Typically combining the existing @ref group_class_ctrl controls in wxDialogs and +wxFrames is sufficient to fullfill any GUI design. +Using the wxWidgets standard controls makes your GUI looks native on all ports +and is obviously easier and faster. + +However there are situations where you need to show some particular kind of data +which is not suited to any existing control. +In these cases rather than hacking an existing control for something it has not +been coinceived for, it's better to write a new widget. + + +@section overview_customwidgets_how How to write the custom widget + +There are at least two very different ways to implement a new widget. + +The first is to build it upon wxWidgets existing classes, thus deriving it from +wxControl or wxWindow. In this way you'll get a @b generic widget. +This method has the advantage that writing a single +implementation works on all ports; the disadvantage is that it the widget will +look the same on all platforms, and thus it may not integrate well with the +native look and feel. + +The second method is to build it directly upon the native toolkits of the platforms you +want to support (e.g. GTK+, Carbon and GDI). In this way you'll get a @b native widget. +This method in fact has the advantage of a native look and feel but requires different +implementations and thus more work. + +In both cases you'll want to better explore some hot topics like: +- @ref overview_windowsizing +- @ref overview_eventhandling_custom to implement your custom widget's events. +You will probably need also to gain some familiarity with the wxWidgets sources, +since you'll need to interface with some undocumented wxWidgets internal mechanisms. + + +@subsection overview_customwidgets_how_generic Writing a generic widget + +Generic widgets are typically derived from wxControl or wxWindow. +They are easy to write. The typical "template" is as follows: + +@code + +enum MySpecialWidgetStyles +{ + SWS_LOOK_CRAZY = 1, + SWS_LOOK_SERIOUS = 2, + SWS_SHOW_BUTTON = 4, + + SWS_DEFAULT_STYLE = (SWS_SHOW_BUTTON|SWS_LOOK_SERIOUS) +}; + +class MySpecialWidget : public wxControl +{ +public: + MySpecialWidget() { Init(); } + + MySpecialWidget(wxWindow *parent, + wxWindowID winid, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = SWS_DEFAULT_STYLE, + const wxValidator& val = wxDefaultValidator, + const wxString& name = "MySpecialWidget") + { + Init(); + + Create(parent, winid, label, pos, size, style, val, name); + } + + bool Create(wxWindow *parent, + wxWindowID winid, + const wxString& label, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = SWS_DEFAULT_STYLE, + const wxValidator& val = wxDefaultValidator, + const wxString& name = wxCollapsiblePaneNameStr); + + // accessors... + +protected: + + void Init() { + // init widget's internals... + } + + virtual wxSize DoGetBestSize() const { + // we need to calculate and return the best size of the widget... + } + + void OnPaint(wxPaintEvent&) { + // draw the widget on a wxDC... + } + +private: + DECLARE_DYNAMIC_CLASS(MySpecialWidget) + DECLARE_EVENT_TABLE() +}; +@endcode + + + +@subsection overview_customwidgets_how_native Writing a native widget + +Writing a native widget is typically more difficult as it requires you to +know the APIs of the platforms you want to support. +See @ref page_port_nativedocs for links to the documentation manuals of the +various toolkits. + +The organization used by wxWidgets consists in: +- declaring the common interface of the control in a generic header, using + the 'Base' postfix; e.g. MySpecialWidgetBase. + See for example the wxWidgets' @c "wx/button.h" file. + +- declaring the real widget class inheriting from the Base version in + platform-specific headers; see for example the wxWidgets' @c "wx/gtk/button.h" file. + +- separing the different implementations in different source files, putting + all common stuff in a separate source. + See for example the wxWidgets' @c "src/common/btncmn.cpp", @c "src/gtk/button.cpp" + and @c "src/msw/button.cpp" files. + +*/ +