X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d958c9bd1754393a2b2e35a95df4df4e74bcd3c4..7b4c31495268b3452019c67e52ff8ff86c03e36c:/docs/latex/wx/txrc.tex diff --git a/docs/latex/wx/txrc.tex b/docs/latex/wx/txrc.tex index ed3d65c95a..c2aa4b4f7c 100644 --- a/docs/latex/wx/txrc.tex +++ b/docs/latex/wx/txrc.tex @@ -2,11 +2,15 @@ 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. +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. @@ -65,43 +69,46 @@ 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 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 \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)$. +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 +\begin{itemize}\itemsep=0pt \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). +\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. +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 -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) @@ -110,58 +117,51 @@ 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} -\subsection{XRC C++ sample}\label{xrccppsample} - -This is the C++ source file (xrcdemo.cpp) for the XRC sample. +\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} -///////////////////////////////////////////////////////////////////////////// -// Name: xmldemo.cpp -// Purpose: XML resources sample -// Author: Vaclav Slavik -// RCS-ID: $Id$ -// Copyright: (c) Vaclav Slavik -// Licence: wxWindows licence -///////////////////////////////////////////////////////////////////////////// - -// ============================================================================ -// declarations -// ============================================================================ + #include + #include + ... + wxFileSystem::AddHandler(new wxZipFSHandler); +\end{verbatim} -// ---------------------------------------------------------------------------- -// headers -// ---------------------------------------------------------------------------- -#ifdef __GNUG__ - #pragma implementation "xrcdemo.cpp" - #pragma interface "xrcdemo.cpp" -#endif +\subsection{Using embedded resources}\label{embeddedresource} -// For compilers that support precompilation, includes "wx/wx.h". -#include "wx/wxprec.h" +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. -#ifdef __BORLANDC__ - #pragma hdrstop -#endif +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} + wxXmlResource::Get()->InitAllHandlers(); + InitXmlResource(); + ... +\end{verbatim} -// 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 +\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" -// ---------------------------------------------------------------------------- -// resources -// ---------------------------------------------------------------------------- // the application icon #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__) #include "rc/appicon.xpm" @@ -206,27 +206,15 @@ private: // 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) + 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() -// 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 // ---------------------------------------------------------------------------- @@ -240,8 +228,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; } // ---------------------------------------------------------------------------- @@ -258,13 +246,11 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar")); } - // 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)) @@ -283,7 +269,6 @@ void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event)) dlg.ShowModal(); } - void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event)) { wxDialog dlg; @@ -298,14 +283,14 @@ This is the XML file (resource.xrc) for the XRC sample. \begin{verbatim} - + - + - + filesave.gif @@ -317,7 +302,7 @@ This is the XML file (resource.xrc) for the XRC sample. - + @@ -455,10 +440,10 @@ This is the XML file (resource.xrc) for the XRC sample. \subsection{XRC file format}\label{xrcfileformat} -This section to be written. +Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows +distribution. \subsection{Adding new resource handlers}\label{newresourcehandlers} -This section to be written. - +Coming soon.