X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/9ecce6913c47685a377509bd16bf246d5ef3feb5..395a82b13fa5f316d2d0dead17701e9bc23337d3:/docs/latex/wx/txrc.tex?ds=sidebyside

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 <edrdo@netcabo.pt>
+%
 \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) <name>: 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 <wx/filesys.h>
+  #include <wx/fs_zip.h>
+  ...
+  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}
+<?xml version="1.0"?>
+<resource version="2.3.0.1">
+    <object class="wxFrame" name="TestWnd_Base">
+        <size>-1,-1</size>
+        <title>Test</title>
+        <object class="wxBoxSizer">
+            <orient>wxHORIZONTAL</orient>
+            <object class="sizeritem">
+                <object class="wxTextCtrl" name="A">
+                    <label>Test label</label>
+                </object>
+            </object>
+            <object class="sizeritem">
+                <object class="wxButton" name="B">
+                    <label>Test button</label>
+                </object>
+            </object>
+        </object>
+    </object>
+</resource>
+
+
+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.
