X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9ecce6913c47685a377509bd16bf246d5ef3feb5..ec59d2ccea39b0225f49e6dd326d4d11940d656d:/docs/latex/wx/txrc.tex diff --git a/docs/latex/wx/txrc.tex b/docs/latex/wx/txrc.tex index d3161078e1..1a2cd4d0f9 100644 --- a/docs/latex/wx/txrc.tex +++ b/docs/latex/wx/txrc.tex @@ -1,3 +1,6 @@ +% Note: -e/C++ header generation documentation added by +% Eduardo Marques +% \section{XML-based resource system overview}\label{xrcoverview} Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler} @@ -9,8 +12,8 @@ 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. +code (the former makes it possible to store all resources in since file and the latter +is useful when you want to embed the resources into the executable). There are several advantages to using XRC resources. @@ -69,45 +72,51 @@ 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 If you are going to use \helpref{XRS files}{binaryresourcefiles}, install +wxFileSystem ZIP handler first with {\tt wxFileSystem::AddHandler(new wxZipFSHandler);} \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");} +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. +To create an XRC file, you can use one of the following methods. -\begin{itemize}\itemsep=0 +\begin{itemize}\itemsep=0pt \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 +\item use \urlref{DialogBlocks}{http://www.anthemion.co.uk/dialogblocks}, a commercial dialog editor; +\item use \urlref{XRCed}{http://xrced.sf.net}, 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 \urlref{Glade}{http://wxglade.sf.net}, a GUI designer written in wxPython. At the moment it can generate Python, C++ and XRC; \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 +A complete list of third-party tools that write to XRC can be found at \urlref{www.wxwindows.org/lnk\_tool.htm}{http://www.wxwindows.org/lnk\_tool.in}. + +It is highly recommended that you use a resource editing tool, 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. +You can pass an XRC file (XML-based text resource file) +or a \helpref{zip-compressed file}{binaryresourcefiles} (extension ZIP or XRS) containing other XRC. -TODO: is the compiled binary format XMB or XRS? How do you handle a C++ resource file? +You can also use \helpref{embedded C++ resources}{embeddedresource} \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 +To compile binary resource files, use the command-line wxrc utility. It takes one or more file parameters +(the input XRC files) and the following switches and options: +\begin{itemize}\itemsep=0pt \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 -c (--cpp-code): write C++ source rather than a XRS file +\item -e (--extra-cpp-code): if used together with -c, generates C++ header file +containing class definitions for the windows defined by the XRC file (see special subsection) \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) @@ -116,13 +125,46 @@ input XRC file) and the following switches and options. \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} +\wxheading{Note} + +XRS file is esentially a renamed ZIP archive which means that you can manipulate +it with standard ZIP tools. Note that if you are using XRS files, you have +to initialize \helpref{wxFileSystem}{wxfilesystem} ZIP handler first! It is a simple +thing to do: + +\begin{verbatim} + #include + #include + ... + wxFileSystem::AddHandler(new wxZipFSHandler); +\end{verbatim} + +\subsection{Using embedded resources}\label{embeddedresource} + +It is sometimes useful to embed resources in the executable itself instead +of loading external file (e.g. when your app is small and consists only of one +exe file). XRC provides means to convert resources into regular C++ file that +can be compiled and included in the executable. + +Use the {\tt -c} switch to +{\tt wxrc} utility to produce C++ file with embedded resources. This file will +contain a function called {\it InitXmlResource} (unless you override this with +a command line switch). Use it to load the resource: + +\begin{verbatim} + extern void InitXMLResource(); // defined in generated file + ... + wxXmlResource::Get()->InitAllHandlers(); + InitXmlResource(); + ... +\end{verbatim} + \subsection{XRC C++ sample}\label{xrccppsample} This is the C++ source file (xrcdemo.cpp) for the XRC sample. @@ -198,8 +240,8 @@ bool MyApp::OnInit() MyFrame *frame = new MyFrame("XML resources demo", wxPoint(50, 50), wxSize(450, 340)); - frame->Show(TRUE); - return TRUE; + frame->Show(true); + return true; } // ---------------------------------------------------------------------------- @@ -219,8 +261,8 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) // event handlers void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event)) { - // TRUE is to force the frame to close - Close(TRUE); + // true is to force the frame to close + Close(true); } void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event)) @@ -413,6 +455,96 @@ This is the XML file (resource.xrc) for the XRC sample. Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows distribution. +\subsection{C++ header file generation}\label{xrccppheader} + +Using the {\tt -e} switch together with {\tt -c}, a C++ header file is written +containing class definitions for the GUI windows defined in the XRC file. +This code generation can make it easier to use XRC and automate program +development. +The classes can be used as basis for development, freeing the +programmer from dealing with most of the XRC specifities (e.g. {\tt XRCCTRL}). + +For each top level window defined in the XRC file a C++ class definition is +generated, containing as class members the named widgets of the window. +A default constructor for each class is also generated. Inside the constructor +all XRC loading is done and all class members representing widgets are initialized. + +A simple example will help understand how the scheme works. Suppose you have +a XRC file defining a top level window {\tt TestWnd\_Base}, which subclasses {\tt wxFrame} (any +other class like {\tt wxDialog} will do also), and has subwidgets {\tt wxTextCtrl} A and {\tt wxButton} B. +The XRC file and corresponding class definition in the header file will be something like: + +\begin{verbatim} + + + + -1,-1 + Test + + wxHORIZONTAL + + + + + + + + + + + + + + + +class TestWnd_Base : public wxFrame { +protected: + wxTextCtrl* A; + wxButton* B; + +private: + void InitWidgetsFromXRC(){ + wxXmlResource::Get()->LoadObject(this,NULL,"TestWnd","wxFrame"); + A = XRCCTRL(*this,"A",wxTextCtrl); + B = XRCCTRL(*this,"B",wxButton); + } +public: +TestWnd::TestWnd(){ + InitWidgetsFromXRC(); + } +}; +\end{verbatim} + +The generated window class can be used as basis for the full window class. The +class members which represent widgets may be accessed by name instead of using +{\tt XRCCTRL} every time you wish to reference them (note that they are {\tt protected} class members), +though you must still use {\tt XRCID} to refer to widget ids in the event +table. + +Example: + +\begin{verbatim} +#include "resource.h" + +class TestWnd : public TestWnd_Base { + public: + TestWnd(){ + // A, B already initialised at this point + A->SetValue("Updated in TestWnd::TestWnd"); + B->SetValue("Nice :)"); + } + void OnBPressed(wxEvent& event){ + Close(); + } + DECLARE_EVENT_TABLE(); +}; + +BEGIN_EVENT_TABLE(TestWnd,TestWnd_Base) +EVT_BUTTON(XRCID("B"),TestWnd::OnBPressed) +END_EVENT_TABLE() + +\end{verbatim} + \subsection{Adding new resource handlers}\label{newresourcehandlers} Coming soon.