\section{XML-based resource system overview}\label{xrcoverview} Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler} {\bf IMPORTANT NOTE:} XRC is not yet a part of the core wxWindows library, so please see the next section for how to compile and link it. Otherwise if you try to use it, you will get link errors. The XML-based resource system, known as XRC, allows user interface elements such as dialogs, menu bars and toolbars, to be stored in text files and loaded into the application at run-time. XRC files can also be compiled into binary XRS files or C++ code, so an XML parser does not need to be linked with the application and load times are faster. There are several advantages to using XRC resources. \begin{itemize}\itemsep=0pt \item Recompiling and linking an application is not necessary if the resources change. \item If you use a dialog designers that generates C++ code, it can be hard to reintegrate this into existing C++ code. Separation of resources and code is a more elegant solution. \item You can choose between different alternative resource files at run time, if necessary. \item The XRC format uses sizers for flexibility, allowing dialogs to be resizable and highly portable. \item The XRC format is a wxWindows standard, and can be generated or postprocessed by any program that understands it. As it is based on the XML standard, existing XML editors can be used for simple editing purposes. \end{itemize} XRC was written by Vaclav Slavik. \subsection{Compiling and using XRC}\label{compilingxrc} XRC can be found under the 'contrib' hierarchy, in the following directories: \begin{verbatim} contrib/src/xrc ; XRC source contrib/include/wx/xrc ; XRC headers contrib/samples/xrc ; XRC sample contrib/utils/wxrc ; XRC resource compiler contrib/utils/wxrcedit ; XRC editor (in progress) \end{verbatim} To compile XRC: \begin{itemize}\itemsep=0pt \item Under Windows using VC++, open the contrib/src/xrc/XrcVC.dsw project and compile. Also compile contrib/utils/wxrc using wxBase if you wish to compile resource files. \item Under Unix, XRC should be configured when you configured wxWindows. Make XRC by changing directory to contrib/src/xrc and type 'make'. Similarly compile contrib/utils/wxrc using wxBase if you wish to compile resource files. {\bf Note:} there is currently a problem with the wxWindows build system that means that only the static version of library can be built at present. \end{itemize} To use XRC: \begin{itemize}\itemsep=0pt \item Under Windows using VC++, link with wxxrc[d].lib. \item Under Unix, link with libwxxrc[d].a. \end{itemize} \subsection{XRC concepts}\label{xrcconcepts} These are the typical steps for using XRC files in your application. \begin{itemize}\itemsep=0pt \item Include the appropriate headers: normally "wx/xrc/xmlres.h" will suffice; \item call {\tt wxXmlResource::Get()->InitAllHandlers()} from your wxApp::OnInit function, and then call {\tt wxXmlResource::Get()->Load("myfile.xrc")} to load the resource file; \item to create a dialog from a resource, create it using the default constructor, and then load using for example {\tt wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1");} \item set up event tables as usual but use the {\tt XRCID(str)} macro to translate from XRC string names to a suitable integer identifier, for example {\tt EVT\_MENU(XRCID("quit"), MyFrame::OnQuit)}. \end{itemize} To create an XRC file, use one of the following methods. \begin{itemize}\itemsep=0 \item Create the file by hand; \item use \urlref{wxDesigner}{http://www.roebling.de}, a commercial dialog designer/RAD tool; \item use \urlref{XRCed}{http://www.mema.ucl.ac.be/~rolinsky/xrced/}, a wxPython-based dialog editor that you can find in the {\tt wxPython/tools} subdirectory of the wxWindows CVS archive; \item use \urlref{wxWorkshop}{http://wxworkshop.sourceforge.net} (under development); \item use wxrcedit ({\tt utils/contrib/wxrcedit}) (under development); \item convert WIN32 RC files to XRC with the tool in {\tt contrib/utils/convertrc}. \end{itemize} It is highly recommended that you use a tool such as wxDesigner, since it's fiddly writing XRC files by hand. You can use \helpref{wxXmlResource::Load}{wxxmlresourceload} in a number of ways. You can pass an XRC file (XML-based text resource file), an XMB file (compiled binary file) or a zip-compressed file (extension ZIP or RSC) containing other XRC or XMB files. TODO: is the compiled binary format XMB or XRS? How do you handle a C++ resource file? \subsection{Using binary resource files}\label{binaryresourcefiles} To compile binary resource files, use the command-line wxrc utility. It takes a single file parameter (the input XRC file) and the following switches and options. \begin{itemize}\itemsep=0 \item -h (--help): show a help message \item -v (--verbose): show verbose logging information \item -c (--cpp-code): write C++ source rather than a RSC file \item -u (--uncompressed): do not compress XML files (C++ only) \item -g (--gettext): output .po catalog (to stdout, or a file if -o is used) \item -n (--function) : specify C++ function name (use with -c) \item -o (--output) : specify the output file, such as resource.xrs or resource.cpp \item -l (--list-of-handlers) : output a list of necessary handlers to this file \end{itemize} For example: \begin{verbatim} % wxrc resource.wrc % wxrc resource.wrc -o resource.wrs % wxrc resource.wrc -v -c -o resource.cpp \end{verbatim} \subsection{XRC C++ sample}\label{xrccppsample} This is the C++ source file (xrcdemo.cpp) for the XRC sample. \begin{verbatim} #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 wxWindows events must use this macro DECLARE_EVENT_TABLE() }; // ---------------------------------------------------------------------------- // event tables and other macros for wxWindows // ---------------------------------------------------------------------------- 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(); } \end{verbatim} \subsection{XRC resource file sample}\label{xrcsample} This is the XML file (resource.xrc) for the XRC sample. \begin{verbatim} filesave.gif 2,2 fileopen.gif Open catalog filesave.gif Save catalog update.gif Update catalog - synchronize it with sources quotes.gif 1 Display quotes around the string? fuzzy.gif Toggled if selected string is fuzzy translation 1 fuzzy.gif fileopen.gif wxALIGN_CENTER 10d wxALL <h1>Hi,</h1>man 100,45d Hello, we are inside a <u>NOTEBOOK</u>... 50,50d Hello, we are inside a <u>NOTEBOOK</u>... 50,50d 1 wxEXPAND wxVERTICAL wxVERTICAL 200,200d Hello, this is an ordinary multiline\n textctrl.... wxEXPAND|wxALL 10 1 10 wxLEFT wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT 10 Second testing dialog \end{verbatim} \subsection{XRC file format}\label{xrcfileformat} Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows distribution. \subsection{Adding new resource handlers}\label{newresourcehandlers} Coming soon.