Applied patch [ 874495 ] wxMSW: Flat buttons

[wxWidgets.git] / docs / latex / wx / txrc.tex

diff --git a/docs/latex/wx/txrc.tex b/docs/latex/wx/txrc.tex
index ed3d65c95aaef348b5134c840d04abded020b27f..970d15847bbf39bf223fe48839b4db36c3698a79 100644 (file)
--- a/docs/latex/wx/txrc.tex
+++ b/docs/latex/wx/txrc.tex
@@ -2,11 +2,15 @@
 
 Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{wxXmlResourceHandler}{wxxmlresourcehandler}
 
 
 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++
 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.
 
 
 There are several advantages to using XRC resources.
 


@@ -65,43 +69,49 @@ 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;
 
 \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
 \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}
 
 \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 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{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{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}
 
 \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.
 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}
 
 
 \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 -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)
 \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)


@@ -110,58 +120,53 @@ input XRC file) and the following switches and options.
 \end{itemize}
 
 For example:
 \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}
 
 \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}
 \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}
+  extern void InitXMLResource(); // defined in generated file
+  ...
+  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"
 
 #include "wx/image.h"
 #include "wx/xrc/xmlres.h"
 

-// ----------------------------------------------------------------------------
-// resources
-// ----------------------------------------------------------------------------

 // the application icon
 #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
     #include "rc/appicon.xpm"
 // the application icon
 #if defined(__WXGTK__) || defined(__WXMOTIF__) || defined(__WXMAC__)
     #include "rc/appicon.xpm"


@@ -206,27 +211,15 @@ private:
 // event tables and other macros for wxWindows
 // ----------------------------------------------------------------------------
 
 // 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)
 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()
 
 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)
 
 IMPLEMENT_APP(MyApp)
 

-// ============================================================================
-// implementation
-// ============================================================================
-

 // ----------------------------------------------------------------------------
 // the application class
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 // the application class
 // ----------------------------------------------------------------------------


@@ -240,8 +233,8 @@ bool MyApp::OnInit()
 
     MyFrame *frame = new MyFrame("XML resources demo",
                                  wxPoint(50, 50), wxSize(450, 340));
 
     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 +251,11 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
     SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
 }
 
     SetToolBar(wxXmlResource::Get()->LoadToolBar(this, "toolbar"));
 }
 

-

 // event handlers
 // event handlers

-

 void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
 {
 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))
 }
 
 void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))


@@ -283,7 +274,6 @@ void MyFrame::OnDlg1(wxCommandEvent& WXUNUSED(event))
     dlg.ShowModal();
 }
 
     dlg.ShowModal();
 }
 

-

 void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
 {
     wxDialog dlg;
 void MyFrame::OnDlg2(wxCommandEvent& WXUNUSED(event))
 {
     wxDialog dlg;


@@ -298,14 +288,14 @@ This is the XML file (resource.xrc) for the XRC sample.
 
 \begin{verbatim}
 <?xml version="1.0"?>
 
 \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">
   <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">
       <style>wxMENU_TEAROFF</style>
       <object class="wxMenuItem" name="menu_about">

-        <label>$About...</label>
+        <label>_About...</label>

         <bitmap>filesave.gif</bitmap>
       </object>
       <object class="separator"/>
         <bitmap>filesave.gif</bitmap>
       </object>
       <object class="separator"/>


@@ -317,7 +307,7 @@ This is the XML file (resource.xrc) for the XRC sample.
       </object>
       <object class="separator"/>
       <object class="wxMenuItem" name="menu_quit">
       </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>
       </object>
     </object>
   </object>


@@ -455,10 +445,10 @@ This is the XML file (resource.xrc) for the XRC sample.
 
 \subsection{XRC file format}\label{xrcfileformat}
 
 
 \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}
 
 
 \subsection{Adding new resource handlers}\label{newresourcehandlers}
 

-This section to be written.
-
+Coming soon.