+\section{XML-based resource system overview}\label{xrcoverview}
+
+Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler}
+
+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 \verb$wxXmlResource::Get()->InitAllHandlers()$ from your wxApp::OnInit function,
+and then call \verb$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 \verb$wxXmlResource::Get()->LoadDialog(&dlg, this, "dlg1")$;
+\item set up event tables as usual but use the \verb$XMLID(str)$ macro to translate from XRC string names
+to a suitable integer identifier, for example \verb$EVT_MENU(XMLID("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};
+\item use wxWorkshop (not yet available);
+\item use wxrcedit (the status of this tool is unknown);
+\item convert WIN32 RC files with the tool in contrib/utils/convertrc (the status of this tool is
+unknown).
+\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) <name>: specify C++ function name (use with -c)
+\item -o (--output) <filename>: specify the output file, such as resource.xrs or resource.cpp
+\item -l (--list-of-handlers) <filename>: 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}
+/////////////////////////////////////////////////////////////////////////////
+// Name: xmldemo.cpp
+// Purpose: XML resources sample
+// Author: Vaclav Slavik
+// RCS-ID: $Id$
+// Copyright: (c) Vaclav Slavik
+// Licence: wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+// ============================================================================
+// declarations
+// ============================================================================
+
+// ----------------------------------------------------------------------------
+// headers
+// ----------------------------------------------------------------------------
+#ifdef __GNUG__
+ #pragma implementation "xrcdemo.cpp"
+ #pragma interface "xrcdemo.cpp"
+#endif
+
+// For compilers that support precompilation, includes "wx/wx.h".
+#include "wx/wxprec.h"
+
+#ifdef __BORLANDC__
+ #pragma hdrstop
+#endif
+
+// for all others, include the necessary headers (this file is usually all you
+// need because it includes almost all "standard" wxWindows headers)
+#ifndef WX_PRECOMP
+ #include "wx/wx.h"
+#endif
+
+#include "wx/image.h"
+#include "wx/xrc/xmlres.h"
+
+// ----------------------------------------------------------------------------
+// resources
+// ----------------------------------------------------------------------------
+// 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
+// ----------------------------------------------------------------------------
+
+// the event tables connect the wxWindows events with the functions (event
+// handlers) which process them. It can be also done at run-time, but for the
+// simple menu events like this the static method is much simpler.
+BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_MENU(XMLID("menu_quit"), MyFrame::OnQuit)
+ EVT_MENU(XMLID("menu_about"), MyFrame::OnAbout)
+ EVT_MENU(XMLID("menu_dlg1"), MyFrame::OnDlg1)
+ EVT_MENU(XMLID("menu_dlg2"), MyFrame::OnDlg2)
+END_EVENT_TABLE()
+
+// Create a new application object: this macro will allow wxWindows to create
+// the application object during program execution (it's better than using a
+// static object for many reasons) and also declares the accessor function
+// wxGetApp() which will return the reference of the right type (i.e. MyApp and
+// not wxApp)
+IMPLEMENT_APP(MyApp)
+
+// ============================================================================
+// implementation
+// ============================================================================
+
+// ----------------------------------------------------------------------------
+// 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}
+<?xml version="1.0"?>
+<resource>
+ <object class="wxMenuBar" name="mainmenu">
+ <style>wxMB_DOCKABLE</style>
+ <object class="wxMenu" name="menu_file">
+ <label>$File</label>
+ <style>wxMENU_TEAROFF</style>
+ <object class="wxMenuItem" name="menu_about">
+ <label>$About...</label>
+ <bitmap>filesave.gif</bitmap>
+ </object>
+ <object class="separator"/>
+ <object class="wxMenuItem" name="menu_dlg1">
+ <label>Dialog 1</label>
+ </object>
+ <object class="wxMenuItem" name="menu_dlg2">
+ <label>Dialog 2</label>
+ </object>
+ <object class="separator"/>
+ <object class="wxMenuItem" name="menu_quit">
+ <label>E$xit\tAlt-X</label>
+ </object>
+ </object>
+ </object>
+ <object class="wxToolBar" name="toolbar">
+ <style>wxTB_FLAT|wxTB_DOCKABLE</style>
+ <margins>2,2</margins>
+ <object class="tool" name="menu_open">
+ <bitmap>fileopen.gif</bitmap>
+ <tooltip>Open catalog</tooltip>
+ </object>
+ <object class="tool" name="menu_save">
+ <bitmap>filesave.gif</bitmap>
+ <tooltip>Save catalog</tooltip>
+ </object>
+ <object class="tool" name="menu_update">
+ <bitmap>update.gif</bitmap>
+ <tooltip>Update catalog - synchronize it with sources</tooltip>
+ </object>
+ <separator/>
+ <object class="tool" name="menu_quotes">
+ <bitmap>quotes.gif</bitmap>
+ <toggle>1</toggle>
+ <tooltip>Display quotes around the string?</tooltip>
+ </object>
+ <object class="separator"/>
+ <object class="tool" name="menu_fuzzy">
+ <bitmap>fuzzy.gif</bitmap>
+ <tooltip>Toggled if selected string is fuzzy translation</tooltip>
+ <toggle>1</toggle>
+ </object>
+ </object>
+ <object class="wxDialog" name="dlg1">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxBitmapButton">
+ <bitmap>fuzzy.gif</bitmap>
+ <focus>fileopen.gif</focus>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxPanel">
+ <object class="wxStaticText">
+ <label>fdgdfgdfgdfg</label>
+ </object>
+ <style>wxSUNKEN_BORDER</style>
+ </object>
+ <flag>wxALIGN_CENTER</flag>
+ </object>
+ <object class="sizeritem">
+ <object class="wxButton">
+ <label>Buttonek</label>
+ </object>
+ <border>10d</border>
+ <flag>wxALL</flag>
+ </object>
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode><h1>Hi,</h1>man</htmlcode>
+ <size>100,45d</size>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxNotebook">
+ <object class="notebookpage">
+ <object class="wxPanel">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
+ <size>50,50d</size>
+ </object>
+ <option>1</option>
+ </object>
+ </object>
+ </object>
+ <label>Page</label>
+ </object>
+ <object class="notebookpage">
+ <object class="wxPanel">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxHtmlWindow">
+ <htmlcode>Hello, we are inside a <u>NOTEBOOK</u>...</htmlcode>
+ <size>50,50d</size>
+ </object>
+ </object>
+ </object>
+ </object>
+ <label>Page 2</label>
+ </object>
+ <usenotebooksizer>1</usenotebooksizer>
+ </object>
+ <flag>wxEXPAND</flag>
+ </object>
+ <orient>wxVERTICAL</orient>
+ </object>
+ </object>
+ <object class="wxDialog" name="dlg2">
+ <object class="wxBoxSizer">
+ <orient>wxVERTICAL</orient>
+ <object class="sizeritem" name="dfgdfg">
+ <object class="wxTextCtrl">
+ <size>200,200d</size>
+ <style>wxTE_MULTILINE|wxSUNKEN_BORDER</style>
+ <value>Hello, this is an ordinary multiline\n textctrl....</value>
+ </object>
+ <option>1</option>
+ <flag>wxEXPAND|wxALL</flag>
+ <border>10</border>
+ </object>
+ <object class="sizeritem">
+ <object class="wxBoxSizer">
+ <object class="sizeritem">
+ <object class="wxButton" name="wxID_OK">
+ <label>Ok</label>
+ <default>1</default>
+ </object>
+ </object>
+ <object class="sizeritem">
+ <object class="wxButton" name="wxID_CANCEL">
+ <label>Cancel</label>
+ </object>
+ <border>10</border>
+ <flag>wxLEFT</flag>
+ </object>
+ </object>
+ <flag>wxLEFT|wxRIGHT|wxBOTTOM|wxALIGN_RIGHT</flag>
+ <border>10</border>
+ </object>
+ </object>
+ <title>Second testing dialog</title>
+ </object>
+</resource>
+\end{verbatim}
+
+\subsection{XRC file format}\label{xrcfileformat}
+
+This section to be written.
+
+\subsection{Adding new resource handlers}\label{newresourcehandlers}
+
+This section to be written.
+
+
projects / wxWidgets.git / commitdiff
