X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f6bb64a625e2aa0234153dae65ee7c24809314e1..3cc305b2b4a0674c56c84d7088cfd70676b850f0:/docs/latex/wx/txrc.tex diff --git a/docs/latex/wx/txrc.tex b/docs/latex/wx/txrc.tex index f412029aad..01558bba48 100644 --- a/docs/latex/wx/txrc.tex +++ b/docs/latex/wx/txrc.tex @@ -8,7 +8,7 @@ Classes: \helpref{wxXmlResource}{wxxmlresource}, \helpref{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 (the former makes it possible to store all resources in since file and the latter +code (the former makes it possible to store all resources in a single file and the latter is useful when you want to embed the resources into the executable). There are several advantages to using XRC resources. @@ -16,7 +16,7 @@ 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 +\item If you use a dialog designer 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. @@ -36,11 +36,11 @@ 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);} +wxFileSystem archive handler first with {\tt wxFileSystem::AddHandler(new wxArchiveFSHandler);} \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 it 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} @@ -54,11 +54,10 @@ To create an XRC file, you can use one of the following methods. \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 wxWidgets 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 convert WIN32 RC files to XRC with the tool in {\tt contrib/utils/convertrc}. +\item use \urlref{wxGlade}{http://wxglade.sf.net}, a GUI designer written in wxPython. At the moment it can generate Python, C++ and XRC; \end{itemize} -A complete list of third-party tools that write to XRC can be found at \urlref{www.wxwidgets.org/lnk\_tool.htm}{http://www.wxwidgets.org/lnk\_tool.in}. +A complete list of third-party tools that write to XRC can be found at \urlref{www.wxwidgets.org/lnk\_tool.htm}{http://www.wxwidgets.org/lnk\_tool.htm}. It is highly recommended that you use a resource editing tool, since it's fiddly writing XRC files by hand. @@ -80,7 +79,7 @@ To compile binary resource files, use the command-line wxrc utility. It takes on \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 -g (--gettext): output underscore-wrapped strings that poEdit or gettext can scan. Outputs to stdout, or a file if -o is used \item -n (--function) : specify C++ function name (use with -c) \item -o (--output) : specify the output file, such as resource.xrs or resource.cpp \item -l (--list-of-handlers) : output a list of necessary handlers to this file @@ -97,20 +96,20 @@ For example: XRS file is essentially 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 +to initialize the \helpref{wxFileSystem}{wxfilesystem} archive handler first! It is a simple thing to do: \begin{verbatim} #include - #include + #include ... - wxFileSystem::AddHandler(new wxZipFSHandler); + wxFileSystem::AddHandler(new wxArchiveFSHandler); \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 +of loading an 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. @@ -321,7 +320,7 @@ This is the XML file (resource.xrc) for the XRC sample. - + wxALIGN_CENTER @@ -380,7 +379,7 @@ This is the XML file (resource.xrc) for the XRC sample. 200,200d - + Hello, this is an ordinary multiline\n textctrl.... @@ -480,7 +479,7 @@ TestWnd::TestWnd(){ 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 +though you must still use {\tt XRCID} to refer to widget IDs in the event table. Example: @@ -507,7 +506,112 @@ END_EVENT_TABLE() \end{verbatim} + + \subsection{Adding new resource handlers}\label{newresourcehandlers} -Coming soon. +Adding a new resource handler is pretty easy. +Typically, to add an handler for the {\tt MyControl} class, you'll want to create +the {\tt xh\_mycontrol.h} {\tt xh\_mycontrol.cpp} files. + +The header needs to contains the {\tt MyControlXmlHandler} class definition: + +\begin{verbatim} +class MyControlXmlHandler : public wxXmlResourceHandler +{ +public: + + // Constructor. + MyControlXmlHandler(); + + // Creates the control and returns a pointer to it. + virtual wxObject *DoCreateResource(); + + // Returns true if we know how to create a control for the given node. + virtual bool CanHandle(wxXmlNode *node); + + // Register with wxWidgets' dynamic class subsystem. + DECLARE_DYNAMIC_CLASS(MyControlXmlHandler) +}; +\end{verbatim} + +The implementation of your custom XML handler will typically look as: + +\begin{verbatim} +// Register with wxWidgets' dynamic class subsystem. +IMPLEMENT_DYNAMIC_CLASS(MyControlXmlHandler, wxXmlResourceHandler) + +MyControlXmlHandler::MyControlXmlHandler() +{ + // this call adds support for all wxWindows class styles + // (e.g. wxBORDER_SIMPLE, wxBORDER_SUNKEN, wxWS_EX_* etc etc) + AddWindowStyles(); + + // if MyControl class supports e.g. MYCONTROL_DEFAULT_STYLE + // you should use: + // XRC_ADD_STYLE(MYCONTROL_DEFAULT_STYLE); +} + +wxObject *MyControlXmlHandler::DoCreateResource() +{ + // the following macro will init a pointer named "control" + // with a new instance of the MyControl class, but will NOT + // Create() it! + XRC_MAKE_INSTANCE(control, MyControl) + + // this is the point where you'll typically need to do the most + // important changes: here the control is created and initialized. + // You'll want to use the wxXmlResourceHandler's getters to + // do most of your work. + // If e.g. the MyControl::Create function looks like: + // + // bool MyControl::Create(wxWindow *parent, int id, + // const wxBitmap &first, const wxPoint &posFirst, + // const wxBitmap &second, const wxPoint &posSecond, + // const wxString &theTitle, const wxFont &titleFont, + // const wxPoint &pos, const wxSize &size, + // long style = MYCONTROL_DEFAULT_STYLE, + // const wxString &name = wxT("MyControl")); + // + // then the XRC for your component should look like: + // + // + // first.xpm + // text.xpm + // 3,3 + // 4,4 + // a title + // + // + // + // + // + // + // and the code to read your custom tags from the XRC file is just: + control->Create(m_parentAsWindow, GetID(), + GetBitmap(wxT("first-bitmap")), + GetPosition(wxT("first-pos")), + GetBitmap(wxT("second-bitmap")), + GetPosition(wxT("second-pos")), + GetText(wxT("the-title")), + GetFont(wxT("title-font")), + GetPosition(), GetSize(), GetStyle(), GetName()); + + SetupWindow(control); + + return control; +} + +bool MyControlXmlHandler::CanHandle(wxXmlNode *node) +{ + // this function tells XRC system that this handler can parse + // the tags + return IsOfClass(node, wxT("MyControl")); +} +\end{verbatim} + +You may want to check the \helpref{wxXmlResourceHandler}{wxxmlresourcehandler} documentation +to see how many built-in getters it contains. It's very easy to retrieve also complex structures +out of XRC files using them.