X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/032e27aad0b1b01bcff49de286dd2120a8aa1177..cd95f7e65c4e1ee61a5d90eb13687ff468cb13ad:/docs/doxygen/overviews/xrc.h
diff --git a/docs/doxygen/overviews/xrc.h b/docs/doxygen/overviews/xrc.h
index 31bae6c52a..cb9aae7c96 100644
--- a/docs/doxygen/overviews/xrc.h
+++ b/docs/doxygen/overviews/xrc.h
@@ -3,10 +3,10 @@
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/*!
+/**
@page overview_xrc XML Based Resource System (XRC)
@@ -36,65 +36,229 @@ There are several advantages to using XRC resources:
XRC was written by Vaclav Slavik.
-@li @ref overview_xrc_concepts
+@li @ref overview_xrc_gettingstarted
+@li @ref overview_xrc_xrcsample
@li @ref overview_xrc_binaryresourcefiles
@li @ref overview_xrc_embeddedresource
-@li @ref overview_xrc_cppsample
-@li @ref overview_xrc_sample
-@li @ref overview_xrc_fileformat
@li @ref overview_xrc_cppheader
@li @ref overview_xrc_newresourcehandlers
+See also the separate @ref overview_xrcformat page for more information, and
+details about the XRC file format.
-
+@section overview_xrc_gettingstarted Getting Started with XRC
-@section overview_xrc_concepts XRC Concepts
+ Creating an XRC file
-These are the typical steps for using XRC files in your application.
+You will need to write an XRC file. Though this @e can be done by hand in a
+text editor, for all but the smallest files it is advisable to use a
+specialised tool. Examples of these include:
-@li Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice.
-@li If you are going to use XRS files (see
- @ref overview_xrc_binaryresourcefiles), install wxFileSystem archive
- handler first with wxFileSystem::AddHandler(new wxArchiveFSHandler);
-@li Call wxXmlResource::Get()->InitAllHandlers() from your wxApp::OnInit
- function, and then call wxXmlResource::Get()->Load("myfile.xrc") to load
- the resource file.
-@li To create a dialog from a resource, create it using the default
- constructor, and then load it. For example:
- wxXmlResource::Get()->LoadDialog(dlg, this, "dlg1");
-@li Set up event tables as usual but use the XRCID(str) macro to translate from
- XRC string names to a suitable integer identifier, for example
- EVT_MENU(XRCID("quit"), MyFrame::OnQuit).
-
-To create an XRC file, you can use one of the following methods.
-
-@li Create the file by hand.
-@li Use wxDesigner , a commercial dialog designer/RAD
- tool.
-@li Use DialogBlocks , a commercial
+@e Non-free:
+@li wxDesigner , a commercial dialog
+ designer/RAD tool.
+@li DialogBlocks , a commercial
dialog editor.
-@li Use XRCed , a wxPython-based dialog editor that you
+
+@e Free:
+@li XRCed , a wxPython-based dialog editor that you
can find in the wxPython/tools subdirectory of the wxWidgets SVN archive.
-@li Use wxGlade , a GUI designer written in wxPython.
- At the moment it can generate Python, C++ and XRC.
+@li wxFormBuilder , a C++-based dialog editor that
+ can output C++, XRC or python.
+
+There's a more complete list at
+
+This small demonstration XRC file contains a simple dialog:
+@code
+
+
+
+
+@endcode
+
+You can keep all your XRC elements together in one file, or split them between
+several.
+
+ Loading XRC files
+
+Before you can use XRC in an app, it must first be loaded. This code fragment
+shows how to load a single XRC file "resource.xrc" from the current working
+directory, plus all the *.xrc files contained in the subdirectory "rc".
+
+@code
+#include "wx/xrc/xmlres.h"
+
+bool MyApp::OnInit()
+{
+ ...
+ wxXmlResource::Get()->InitAllHandlers();
+
+ wxXmlResource::Get()->Load("resource.xrc");
+ wxXmlResource::Get()->LoadAllFiles("rc");
+ ...
+}
+@endcode
+
+It's normal to load any XRC files at the beginning of an app. Though it is
+possible to unload a file later, it's seldom necessary.
+
+
+ Using an XRC item
+
+The XRC file(s) are now loaded into the app's virtual filesystem. From there,
+you must do another sort of load when you want to use an individual object.
+Yes, it's confusingly named, but you first Load() the file, and later load each
+top-level object when its needed.
+
+This is how you would use the above simple dialog in your code.
+
+@code
+void MyClass::ShowDialog()
+{
+ wxDialog dlg;
+ if (wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
+ dlg.ShowModal();
+}
+@endcode
+
+See how simple the code is. All the instantiation is done invisibly by the XRC
+system.
+
+Though you'll most often use wxXmlResource::LoadDialog, there are also
+equivalents that load a frame, a menu etc; and the generic
+wxXmlResource::LoadObject. See wxXmlResource for more details.
+
+ Accessing XRC child controls
+
+The last section showed how to load top-level windows like dialogs, but what
+about child windows like the wxTextCtrl named "text" that the dialog contains?
+You can't 'load' an individual child control in the same way. Instead you use
+the XRCCTRL macro to get a pointer to the child. To expand the previous code:
+
+@code
+void MyClass::ShowDialog()
+{
+ wxDialog dlg;
+ if (!wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
+ return;
+
+ wxTextCtrl* pText = XRCCTRL(dlg, "text", wxTextCtrl);
+ if (pText)
+ pText->ChangeValue("This is a simple dialog");
+
+ dlg.ShowModal();
+}
+@endcode
+
+XRCCTRL takes a reference to the parent container and uses wxWindow::FindWindow
+to search inside it for a wxWindow with the supplied name (here "text"). It
+returns a pointer to that control, cast to the type in the third parameter; so
+a similar effect could be obtained by writing:
+
+@code
+pText = (wxTextCtrl*)(dlg.FindWindowByName("text"));
+@endcode
+
+ XRC and IDs
+
+The ID of a control is often needed, e.g. for use in an event table
+or with wxEvtHandler::Bind. It can easily be found by passing the name of the
+control to the XRCID macro:
+
+@code
+void MyClass::ShowDialog()
+{
+ wxDialog dlg;
+ if (!wxXmlResource::Get()->LoadDialog(&dlg, NULL, "SimpleDialog"))
+ return;
+
+ XRCCTRL(dlg, "text", wxTextCtrl)->Bind(wxEVT_COMMAND_TEXT_UPDATED,
+ wxTextEventHandler(MyClass::OnTextEntered), this, XRCID("text"));
+
+ XRCCTRL(dlg, "clickme_btn", wxButton)->Bind(wxEVT_COMMAND_BUTTON_CLICKED,
+ wxCommandEventHandler(MyClass::OnClickme), this, XRCID("clickme_btn"));
-A complete list of third-party tools that write to XRC can be found at
-.
+ dlg.ShowModal();
+}
+@endcode
+
+A few points to note:
+@li The value of the int returned by XRCID("foo") is guaranteed to be unique
+within an app.
+@li However that value isn't predictable, and you shouldn't rely on it being
+consistent between runs. It certainly won't be the same in different apps.
+@li @ref page_stockitems such as wxID_OK work correctly without requiring XRCID
+(because, internally, XRCID("wxID_OK") is mapped to wxID_OK).
+@li Both XRCID and XRCCTRL use the 'name' of the control (as in
+wxWindow::GetName). This is different from the label that the user sees on
+e.g. a wxButton.
+
+ Subclassing in XRC
+
+You will often want to use subclassed wx controls in your code. There are three
+ways to do this from XRC:
+@li Very rarely you might need to
+@ref overview_xrcformat_extending_custom "create your own wxXmlResourceHandler"
+@li Occasionally wxXmlResource::AttachUnknownControl may be best. See
+@ref overview_xrcformat_extending_unknown
+@li Usually though, the simple 'subclass' keyword will suffice.
+
+Suppose you wanted the wxTextCtrl named "text" to be created as your derived
+class MyTextCtrl. The only change needed in the XRC file would be in this line:
+
+@code
+
+@endcode
-It is highly recommended that you use a resource editing tool, since it's
-fiddly writing XRC files by hand.
+The only change in your code would be to use MyTextCtrl in XRCCTRL. However for
+the subclass to be created successfully, it's important to ensure that it uses
+wxWidget's RTTI mechanism: see @ref overview_xrcformat_extending_subclass for
+the details.
-You can use wxXmlResource::Load in a number of ways. You can pass an XRC file
-(XML-based text resource file) or a zip-compressed file (see
-@ref overview_xrc_binaryresourcefiles), with extension ZIP or XRS, containing
-other XRC.
-You can also use embedded C++ resources (see
-@ref overview_xrc_embeddedresource).
+@section overview_xrc_xrcsample The XRC sample
-@section overview_xrc_binaryresourcefiles Using Binary Resource Files
+A major resource for learning how to use XRC is the @sample{xrc}. This
+demonstrates all of the standard uses of XRC, and some of the less common ones.
+It is strongly suggested that you run it, and look at the well-commented
+source code to see how it works.
+
+
+@section overview_xrc_binaryresourcefiles Binary Resource Files
To compile binary resource files, use the command-line @c wxrc utility. It
takes one or more file parameters (the input XRC files) and the following
@@ -156,300 +320,6 @@ InitXmlResource();
@endcode
-@section overview_xrc_cppsample XRC C++ Sample
-
-This is the C++ source file (xrcdemo.cpp) for the XRC sample.
-
-@code
-#include "wx/wx.h"
-#include "wx/image.h"
-#include "wx/xrc/xmlres.h"
-
-// the application icon
-#if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
- #include "rc/appicon.xpm"
-#endif
-
-// ----------------------------------------------------------------------------
-// private classes
-// ----------------------------------------------------------------------------
-
-// Define a new application type, each program should derive a class from wxApp
-class MyApp : public wxApp
-{
-public:
- // override base class virtuals
- // ----------------------------
-
- // this one is called on application startup and is a good place for the
- // app initialization (doing it here and not in the ctor allows to have an
- // error return: if OnInit() returns false, the application terminates)
- virtual bool OnInit();
-};
-
-// Define a new frame type: this is going to be our main frame
-class MyFrame : public wxFrame
-{
-public:
- // ctor(s)
- MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
-
- // event handlers (these functions should _not_ be virtual)
- void OnQuit(wxCommandEvent& event);
- void OnAbout(wxCommandEvent& event);
- void OnDlg1(wxCommandEvent& event);
- void OnDlg2(wxCommandEvent& event);
-
-private:
- // any class wishing to process wxWidgets events must use this macro
- DECLARE_EVENT_TABLE()
-};
-
-// ----------------------------------------------------------------------------
-// event tables and other macros for wxWidgets
-// ----------------------------------------------------------------------------
-
-BEGIN_EVENT_TABLE(MyFrame, wxFrame)
- EVT_MENU(XRCID("menu_quit"), MyFrame::OnQuit)
- EVT_MENU(XRCID("menu_about"), MyFrame::OnAbout)
- EVT_MENU(XRCID("menu_dlg1"), MyFrame::OnDlg1)
- EVT_MENU(XRCID("menu_dlg2"), MyFrame::OnDlg2)
-END_EVENT_TABLE()
-
-IMPLEMENT_APP(MyApp)
-
-// ----------------------------------------------------------------------------
-// the application class
-// ----------------------------------------------------------------------------
-
-// 'Main program' equivalent: the program execution "starts" here
-bool MyApp::OnInit()
-{
- wxImage::AddHandler(new wxGIFHandler);
- wxXmlResource::Get()->InitAllHandlers();
- wxXmlResource::Get()->Load("rc/resource.xrc");
-
- MyFrame *frame = new MyFrame("XML resources demo",
- wxPoint(50, 50), wxSize(450, 340));
- frame->Show(true);
- return true;
-}
-
-// ----------------------------------------------------------------------------
-// main frame
-// ----------------------------------------------------------------------------
-
-// frame constructor
-MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
-: wxFrame((wxFrame *)NULL, -1, title, pos, size)
-{
- SetIcon(wxICON(appicon));
-
- SetMenuBar(wxXmlResource::Get()->LoadMenuBar("mainmenu"));
- SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
-}
-
-// event handlers
-void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
-{
- // true is to force the frame to close
- Close(true);
-}
-
-void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
-{
- wxString msg;
- msg.Printf( _T("This is the about dialog of XML resources demo.\n")
- _T("Welcome to %s"), wxVERSION_STRING);
-
- wxMessageBox(msg, "About XML resources demo",
- wxOK | wxICON_INFORMATION, this);
-}
-
-void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
-{
- wxDialog dlg;
- wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");
- dlg.ShowModal();
-}
-
-void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
-{
- wxDialog dlg;
- wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg2");
- dlg.ShowModal();
-}
-@endcode
-
-
-@section overview_xrc_sample XRC Resource File Sample
-
-This is the XML file (resource.xrc) for the XRC sample.
-
-@code
-
-
-
-
-
-
-
-@endcode
-
-
-@section overview_xrc_fileformat XRC File Format
-
-Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWidgets
-distribution.
-
-
@section overview_xrc_cppheader C++ header file generation
Using the @c -e switch together with @c -c, a C++ header file is written
@@ -466,7 +336,7 @@ initialized.
A simple example will help understand how the scheme works. Suppose you have a
XRC file defining a top level window @c TestWnd_Base, which subclasses wxFrame
-(any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A
+(any other class like @c wxDialog will do also), and has subwidgets wxTextCtrl A
and wxButton B.
The XRC file and corresponding class definition in the header file will be
@@ -624,7 +494,7 @@ wxObject *MyControlXmlHandler::DoCreateResource()
// do most of your work.
// If e.g. the MyControl::Create function looks like:
//
- // bool MyControl::Create(wxWindow *parent, int id,
+ // bool MyControl::Create(wxWindow *parent, int id,
// const wxBitmap &first, const wxPoint &posFirst,
// const wxBitmap &second, const wxPoint &posSecond,
// const wxString &theTitle, const wxFont &titleFont,