X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d958c9bd1754393a2b2e35a95df4df4e74bcd3c4..aad035b2f51cc206edc0b888695dfb5c8d53687a:/docs/latex/wx/xmlres.tex diff --git a/docs/latex/wx/xmlres.tex b/docs/latex/wx/xmlres.tex index 214f28ef24..0f924330d2 100644 --- a/docs/latex/wx/xmlres.tex +++ b/docs/latex/wx/xmlres.tex @@ -3,13 +3,13 @@ % xmlres.h at 22/Jan/02 23:08:28 % - \section{\class{wxXmlResource}}\label{wxxmlresource} +This is the main class for interacting with the XML-based resource system. + +The class holds XML resources from one or more .xml files, binary files or zip archive files. -This class holds XML resources from one or more .xml files -(or derived forms, either binary or zipped -- see manual for -details). +See \helpref{XML-based resource system overview}{xrcoverview} for details. \wxheading{Derived from} @@ -17,33 +17,57 @@ details). \wxheading{Include files} - + + +\wxheading{Constants} -\wxheading{Data structures} +\begin{verbatim} +enum wxXmlResourceFlags +{ + wxXRC_USE_LOCALE = 1, + wxXRC_NO_SUBCLASSING = 2, + wxXRC_NO_RELOADING = 4 +}; +\end{verbatim} \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxXmlResource::wxXmlResource}\label{wxxmlresourcewxxmlresource} +\membersection{wxXmlResource::wxXmlResource}\label{wxxmlresourcector} -\func{}{wxXmlResource}{\param{const wxString\& }{filemask}, \param{int }{flags = wxXRC\_USE\_LOCALE}} +\func{}{wxXmlResource}{\param{const wxString\& }{filemask}, + \param{int }{flags = wxXRC\_USE\_LOCALE}, + \param{const wxString& }{domain = wxEmptyString}} Constructor. -Flags: wxXRC\_USE\_LOCALE -translatable strings will be translated via \_() -wxXRC\_NO\_SUBCLASSING -subclass property of object nodes will be ignored -(useful for previews in XRC editors) +\docparam{filemask}{The XRC file, archive file, or wildcard specification that will be used to +load all resource files inside a zip archive.} + +\docparam{flags}{wxXRC\_USE\_LOCALE: translatable strings will be translated via \_(). +wxXRC\_NO\_SUBCLASSING: subclass property of object nodes will be ignored +(useful for previews in XRC editors).} + +\docparam{domain}{The name of the gettext catalog to search for + translatable strings. By default all loaded catalogs will be + searched. This provides a way to allow the strings to only come + from a specific catalog.} -\func{}{wxXmlResource}{\param{int }{flags = wxXRC\_USE\_LOCALE}} +\func{}{wxXmlResource}{\param{int }{flags = wxXRC\_USE\_LOCALE}, + \param{const wxString& }{domain = wxEmptyString}} Constructor. -Flags: wxXRC\_USE\_LOCALE -translatable strings will be translated via \_() -wxXRC\_NO\_SUBCLASSING -subclass property of object nodes will be ignored -(useful for previews in XRC editors) + +\docparam{flags}{wxXRC\_USE\_LOCALE: translatable strings will be translated via \_(). +wxXRC\_NO\_SUBCLASSING: subclass property of object nodes will be ignored +(useful for previews in XRC editors). wxXRC\_NO\_RELOADING will prevent the +XRC files from being reloaded from disk in case they have been modified there +since being last loaded (may slightly speed up loading them).} + +\docparam{domain}{The name of the gettext catalog to search for + translatable strings. By default all loaded catalogs will be + searched. This provides a way to allow the strings to only come + from a specific catalog.} \membersection{wxXmlResource::\destruct{wxXmlResource}}\label{wxxmlresourcedtor} @@ -57,11 +81,13 @@ Destructor. \func{void}{AddHandler}{\param{wxXmlResourceHandler* }{handler}} -Initialize only a specific handler (or custom handler). Convention says -that handler name is equal to the control's name plus 'XmlHandler', for example +Initializes only a specific handler (or custom handler). Convention says +that the handler name is equal to the control's name plus 'XmlHandler', for example wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler -(xmlres) can create include file that contains initialization code for -all controls used within the resource. +(wxxrc) can create include file that contains initialization code for +all controls used within the resource. Note that this handler should be +allocated on the heap, since it will be delete by +\helpref{ClearHandlers}{wxxmlresourceclearhandlers} later. \membersection{wxXmlResource::AttachUnknownControl}\label{wxxmlresourceattachunknowncontrol} @@ -76,43 +102,22 @@ Unknown controls are used in conjunction with . \func{void}{ClearHandlers}{\void} -Removes all handlers +Removes all handlers and deletes them (this means that any handlers added using +\helpref{AddHandler}{wxxmlresourceaddhandler} must be allocated on the heap). \membersection{wxXmlResource::CompareVersion}\label{wxxmlresourcecompareversion} \constfunc{int}{CompareVersion}{\param{int }{major}, \param{int }{minor}, \param{int }{release}, \param{int }{revision}} -Compares resources version to argument. Returns -1 if resources version -is less than the argument, +1 if greater and 0 if they equal. - - -\membersection{wxXmlResource::CreateResFromNode}\label{wxxmlresourcecreateresfromnode} - -\func{wxObject*}{CreateResFromNode}{\param{wxXmlNode* }{node}, \param{wxObject* }{parent}, \param{wxObject* }{instance = NULL}} - -Creates a resource from information in the given node. - - -\membersection{wxXmlResource::DoFindResource}\label{wxxmlresourcedofindresource} - -\func{wxXmlNode*}{DoFindResource}{\param{wxXmlNode* }{parent}, \param{const wxString\& }{name}, \param{const wxString\& }{classname}, \param{bool }{recursive}} - -Helper function: finds a resource (calls UpdateResources) and returns a node containing it. - - -\membersection{wxXmlResource::FindResource}\label{wxxmlresourcefindresource} - -\func{wxXmlNode*}{FindResource}{\param{const wxString\& }{name}, \param{const wxString\& }{classname}, \param{bool }{recursive = FALSE}} - -Finds a resource (calls UpdateResources) and returns a node containing it. +Compares the XRC version to the argument. Returns -1 if the XRC version +is less than the argument, +1 if greater, and 0 if they equal. \membersection{wxXmlResource::Get}\label{wxxmlresourceget} \func{wxXmlResource*}{Get}{\void} -Singleton accessors. Gets the global resources object or creates one if none exists. @@ -127,25 +132,27 @@ Returns flags, which may be a bitlist of wxXRC\_USE\_LOCALE and wxXRC\_NO\_SUBCL \constfunc{long}{GetVersion}{\void} -Returns version information (a.b.c.d = d+ 256*c + 256\verb|^|2*b + 256\verb|^|3*a). - +Returns version information (a.b.c.d = d+ 256*c + 256\textasciicircum2*b + 256\textasciitilde3*a). -\membersection{wxXmlResource::GetXMLID}\label{wxxmlresourcegetxmlid} -\func{int}{GetXMLID}{\param{const wxChar* }{str\_id}} +\membersection{wxXmlResource::GetXRCID}\label{wxxmlresourcegetxmlid} -Returns a numeric ID that is equivalent to the string id used in an XML -resource. To be used in event tables. -Macro XMLID is provided for convenience +\func{int}{GetXRCID}{\param{const wxChar* }{str\_id}, \param{int }{value\_if\_not\_found = -2}} +Returns a numeric ID that is equivalent to the string ID used in an XML +resource. If an unknown \arg{str\_id} is requested (i.e. other than wxID\_XXX +or integer), a new record is created which associates the given string with +a number. If \arg{value\_if\_not\_found} is \texttt{wxID\_NONE}, the number is obtained via +\helpref{wxNewId()}{wxnewid}. Otherwise \arg{value\_if\_not\_found} is used. +Macro {\tt XRCID(name)} is provided for convenient use in event tables. \membersection{wxXmlResource::InitAllHandlers}\label{wxxmlresourceinitallhandlers} \func{void}{InitAllHandlers}{\void} -Initialize handlers for all supported controls/windows. This will +Initializes handlers for all supported controls/windows. This will make the executable quite big because it forces linking against -most of the wxWindows library. +most of the wxWidgets library. \membersection{wxXmlResource::Load}\label{wxxmlresourceload} @@ -167,18 +174,22 @@ Loads a bitmap resource from a file. \func{wxDialog*}{LoadDialog}{\param{wxWindow* }{parent}, \param{const wxString\& }{name}} -Loads a dialog. dlg points to parent window (if any). - +Loads a dialog. {\it dlg} points to a parent window (if any). \func{bool}{LoadDialog}{\param{wxDialog* }{dlg}, \param{wxWindow* }{parent}, \param{const wxString\& }{name}} -Loads a dialog. dlg points to parent window (if any). This form -is used to finish creation of already existing instance (main reason -for this is that you may want to use derived class with new event table) -Example (typical usage): -MyDialog dlg; -wxTheXmlResource->LoadDialog(\&dlg, mainFrame, "my\_dialog"); -dlg->ShowModal(); +Loads a dialog. {\it dlg} points to parent window (if any). + +This form is used to finish creation of an already existing instance (the main reason +for this is that you may want to use derived class with a new event table). + +Example: + +\begin{verbatim} + MyDialog dlg; + wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog"); + dlg->ShowModal(); +\end{verbatim} \membersection{wxXmlResource::LoadFrame}\label{wxxmlresourceloadframe} @@ -206,25 +217,23 @@ Loads menu from resource. Returns NULL on failure. \func{wxMenuBar*}{LoadMenuBar}{\param{wxWindow* }{parent}, \param{const wxString\& }{name}} -Loads menubar from resource. Returns NULL on failure. - +Loads a menubar from resource. Returns NULL on failure. \func{wxMenuBar*}{LoadMenuBar}{\param{const wxString\& }{name}} -Loads menubar from resource. Returns NULL on failure. +Loads a menubar from resource. Returns NULL on failure. \membersection{wxXmlResource::LoadPanel}\label{wxxmlresourceloadpanel} \func{wxPanel*}{LoadPanel}{\param{wxWindow* }{parent}, \param{const wxString\& }{name}} -Loads a panel. panel points to parent window (if any). - +Loads a panel. {\it panel} points to parent window (if any). \func{bool}{LoadPanel}{\param{wxPanel* }{panel}, \param{wxWindow* }{parent}, \param{const wxString\& }{name}} -Loads a panel. panel points to parent window (if any). This form -is used to finish creation of already existing instance. +Loads a panel. {\it panel} points to parent window (if any). This form +is used to finish creation of an already existing instance. \membersection{wxXmlResource::LoadToolBar}\label{wxxmlresourceloadtoolbar} @@ -241,10 +250,37 @@ Loads a toolbar. Sets the global resources object and returns a pointer to the previous one (may be NULL). -\membersection{wxXmlResource::UpdateResources}\label{wxxmlresourceupdateresources} +\membersection{wxXmlResource::SetFlags}\label{wxxmlresourcesetflags} + +\func{void}{SetFlags}{\param{int }{flags}} + +Sets flags (bitlist of wxXRC\_USE\_LOCALE and wxXRC\_NO\_SUBCLASSING). + + +\membersection{wxXmlResource::Unload}\label{wxxmlresourceunload} + +\func{bool}{Unload}{\param{const wxString\& }{filename}} + +This function unloads a resource previously loaded by +\helpref{Load()}{wxxmlresourceload}. + +Returns \true if the resource was successfully unloaded and \false if it hasn't +been found in the list of loaded resources. + + + +\membersection{wxXmlResource::GetDomain}\label{wxxmlresourcegetdomain} + +\func{wxChar*}{GetDomain}{} + +Returns the domain (message catalog) that will be used to load +translatable strings in the XRC. + + +\membersection{wxXmlResource::SetDomain}\label{wxxmlresourcesetdomain} -\func{void}{UpdateResources}{\void} +\func{wxChar*}{SetDomain}{\param{const wxChar* }{domain}} -Scans the resources list for unloaded files and loads them. Also reloads -files that have been modified since last loading. +Sets the domain (message catalog) that will be used to load +translatable strings in the XRC.