Added first cut at XRC docs; added font spec for wxWindows manual (new Tex2RTF feature!);
removed section on porting from 1.x. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@13766 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart
464
docs/latex/wx/txrc.tex
Normal file
464
docs/latex/wx/txrc.tex
Normal file
@@ -0,0 +1,464 @@
|
||||
\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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user