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.
\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}, a commercial dialog designer/RAD tool;
\item use \urlref{XRCed}{http://www.mema.ucl.ac.be/~rolinsky/xrced/}, a wxPython-based
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) <name>: specify C++ function name (use with -c)
\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 <wx/filesys.h>
+ #include <wx/fs_zip.h>
+ ...
+ 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"
// 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
// ----------------------------------------------------------------------------
SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
}
-
// event handlers
-
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
// TRUE is to force the frame to close
dlg.ShowModal();
}
-
void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
{
wxDialog dlg;
\begin{verbatim}
<?xml version="1.0"?>
-<resource>
+<resource version="2.3.0.1">
<object class="wxMenuBar" name="mainmenu">
<style>wxMB_DOCKABLE</style>
<object class="wxMenu" name="menu_file">
- <label>$File</label>
+ <label>_File</label>
<style>wxMENU_TEAROFF</style>
<object class="wxMenuItem" name="menu_about">
- <label>$About...</label>
+ <label>_About...</label>
<bitmap>filesave.gif</bitmap>
</object>
<object class="separator"/>
</object>
<object class="separator"/>
<object class="wxMenuItem" name="menu_quit">
- <label>E$xit\tAlt-X</label>
+ <label>E_xit\tAlt-X</label>
</object>
</object>
</object>
\subsection{XRC file format}\label{xrcfileformat}
-\subsubsection{Introduction to the XRC file format}\label{xrcfileformatintro}
-
-This note describes the file format used for storing XRC resources that are
-used by wxXmlResource class. It is probably only useful for those implementing
-dialog editors with XRC support, or for those writing XRC files by hand.
-
-If you only want to use the resources, you can choose from a number of editors,
-as listed in \helpref{XRC concepts}{xrcconcepts}.
-
-The XRC format is based on XML 1.0 (please consult W3C's specification). There
-is no DTD available since it is not possible to fully describe the format with
-the limited expressive power of DTDs.
-
-\subsubsection{XRC terminology}\label{xrcterminology}
-
-The usual XML terminology applies. In particular, we shall use the terms
-{\it node}, {\it property} and {\it value} in the XML sense:
-
-\begin{verbatim}
- <node property1="value1" property2="value2">...</node>
-\end{verbatim}
-
-The term "attribute" is specific to XRC and refers to a property-less subnode
-of an <object> or <object_ref> node. In the example bellow, <pos>, <label> and
-<style> are attributes, while neither <resource> nor either of <object>s is:
-
-\begin{verbatim}
- <?xml version="1.0" encoding="utf-8">
- <resource version="2.3.0.1">
- <object class="wxPanel">
- <style>wxSUNKEN_BORDER</style>
- <object class="wxStaticText">
- <label>A label</label>
- <pos>10,10</pos>
- </object>
- </object>
- </resource>
-\end{verbatim}
-
-\subsubsection{XRC format high-level description}
-
-An XRC resource file is a well-formed XML 1.0 document.
-
-The root node of XRC document must be <resource>. The <resource> node has
-optional {\it version} property. Default version (in absence of the version
-property) is "0.0.0.0". The version consists of four integers separated by
-periods. Version of XRC format changes only if there was an incompatible
-change introduced (i.e. either the library cannot understand old resource
-files or older versions of the library wouldn't understand the new format).
-The first three integers are major, minor and release number of the wxWindows
-release when the change was introduced, the last one is revision number and
-is 0 for the first incompatible change in given wxWindows release, 1 for
-the second, and so on.
-
-Differences between versions are described within this document in paragraphs
-entitled {\it Version Note}.
-
-The <resource> node is only allowed to have <object> and <object_ref>
-subnodes, all of which must have the "name" property.
-
-<object> - TODO (name, class, subclass)
-
-<object_ref> - TODO (name, ref, subclass)
-
-\subsubsection{Common XRC attributes}
-
-Coming soon.
-
-\subsubsection{Supported classes}
-
-Coming soon.
+Please see Technical Note 14 (docs/tech/tn0014.txt) in your wxWindows
+distribution.
\subsection{Adding new resource handlers}\label{newresourcehandlers}
projects / wxWidgets.git / blobdiff