.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2018 by Total Control Software License: wxWindows License .. include:: headings.inc .. _wx.xrc.XmlResource: ========================================================================================================================================== |phoenix_title| **wx.xrc.XmlResource** ========================================================================================================================================== 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. Note that this is a singleton class and you'll never allocate/deallocate it. Just use the static :meth:`wx.xrc.XmlResource.Get` getter. .. seealso:: :ref:`XML Based Resource System ` , :ref:`XRC File Format ` | |class_hierarchy| Class Hierarchy ================================= .. raw:: html
Inheritance diagram for class XmlResource:

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~wx.xrc.XmlResource.__init__` Constructor. :meth:`~wx.xrc.XmlResource.AddHandler` Initializes only a specific handler (or custom handler). :meth:`~wx.xrc.XmlResource.AddSubclassFactory` Registers subclasses factory for use in ``XRC``. :meth:`~wx.xrc.XmlResource.AttachUnknownControl` Attaches an unknown control to the given panel/window/dialog. :meth:`~wx.xrc.XmlResource.ClearHandlers` Removes all handlers and deletes them (this means that any handlers added using :meth:`~XmlResource.AddHandler` must be allocated on the heap). :meth:`~wx.xrc.XmlResource.CompareVersion` Compares the ``XRC`` version to the argument. :meth:`~wx.xrc.XmlResource.FindXRCIDById` Returns a string ``ID`` corresponding to the given numeric ``ID``. :meth:`~wx.xrc.XmlResource.Get` Gets the global resources object or creates one if none exists. :meth:`~wx.xrc.XmlResource.GetDomain` Returns the domain (message catalog) that will be used to load translatable strings in the ``XRC``. :meth:`~wx.xrc.XmlResource.GetFlags` Returns flags, which may be a bitlist of :ref:`wx.xrc.XmlResourceFlags` enumeration values. :meth:`~wx.xrc.XmlResource.GetResourceNode` Returns the :ref:`wx.xml.XmlNode` containing the definition of the object with the given name or ``None``. :meth:`~wx.xrc.XmlResource.GetVersion` Returns version information (a.b.c.d = d + 256c + 2562b + 2563a). :meth:`~wx.xrc.XmlResource.GetXRCID` Returns a numeric ``ID`` that is equivalent to the string ``ID`` used in an ``XML`` resource. :meth:`~wx.xrc.XmlResource.InitAllHandlers` Initializes handlers for all supported controls/windows. :meth:`~wx.xrc.XmlResource.InsertHandler` Add a new handler at the begining of the handler list. :meth:`~wx.xrc.XmlResource.Load` Loads resources from ``XML`` files that match given filemask. :meth:`~wx.xrc.XmlResource.LoadAllFiles` Loads all .xrc files from directory `dirname`. :meth:`~wx.xrc.XmlResource.LoadBitmap` Loads a bitmap resource from a file. :meth:`~wx.xrc.XmlResource.LoadDialog` Loads a dialog. :meth:`~wx.xrc.XmlResource.LoadFile` Simpler form of :meth:`~XmlResource.Load` for loading a single ``XRC`` file. :meth:`~wx.xrc.XmlResource.LoadFrame` Loads a frame from the resource. :meth:`~wx.xrc.XmlResource.LoadFromBuffer` Load the resource from a bytes string or other data buffer compatible object. :meth:`~wx.xrc.XmlResource.LoadIcon` Loads an icon resource from a file. :meth:`~wx.xrc.XmlResource.LoadMenu` Loads menu from resource. :meth:`~wx.xrc.XmlResource.LoadMenuBar` Loads a menubar from resource. :meth:`~wx.xrc.XmlResource.LoadObject` Load an object from the resource specifying both the resource name and the class name. :meth:`~wx.xrc.XmlResource.LoadObjectRecursively` Load an object from anywhere in the resource tree. :meth:`~wx.xrc.XmlResource.LoadPanel` Loads a panel. :meth:`~wx.xrc.XmlResource.LoadToolBar` Loads a toolbar. :meth:`~wx.xrc.XmlResource.Set` Sets the global resources object and returns a pointer to the previous one (may be ``None``). :meth:`~wx.xrc.XmlResource.SetDomain` Sets the domain (message catalog) that will be used to load translatable strings in the ``XRC``. :meth:`~wx.xrc.XmlResource.SetFlags` Sets flags (bitlist of :ref:`wx.xrc.XmlResourceFlags` enumeration values). :meth:`~wx.xrc.XmlResource.Unload` This function unloads a resource previously loaded by :meth:`~XmlResource.Load` . ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~wx.xrc.XmlResource.Domain` See :meth:`~wx.xrc.XmlResource.GetDomain` and :meth:`~wx.xrc.XmlResource.SetDomain` :attr:`~wx.xrc.XmlResource.Flags` See :meth:`~wx.xrc.XmlResource.GetFlags` and :meth:`~wx.xrc.XmlResource.SetFlags` :attr:`~wx.xrc.XmlResource.Version` See :meth:`~wx.xrc.XmlResource.GetVersion` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: wx.xrc.XmlResource(Object) **Possible constructors**:: XmlResource(filemask, flags=XRC_USE_LOCALE, domain="") XmlResource(flags=XRC_USE_LOCALE, domain="") This is the main class for interacting with the XML-based resource system. .. method:: __init__(self, *args, **kw) |overload| Overloaded Implementations: **~~~** **__init__** `(self, filemask, flags=XRC_USE_LOCALE, domain="")` Constructor. :param `filemask`: The ``XRC`` file, archive file, or wildcard specification that will be used to load all resource files inside a zip archive. :type `filemask`: string :param `flags`: One or more value of the :ref:`wx.xrc.XmlResourceFlags` enumeration. :type `flags`: int :param `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. :type `domain`: string **~~~** **__init__** `(self, flags=XRC_USE_LOCALE, domain="")` Constructor. :param `flags`: One or more value of the :ref:`wx.xrc.XmlResourceFlags` enumeration. :type `flags`: int :param `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. :type `domain`: string **~~~** .. method:: AddHandler(self, handler) 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 TextCtrlXmlHandler, HtmlWindowXmlHandler. The ``XML`` resource compiler (wxxrc) can create include file that contains initialization code for all controls used within the resource. Note that this handler must be allocated on the heap, since it will be deleted by :meth:`ClearHandlers` later. :param `handler`: :type `handler`: wx.xrc.XmlResourceHandler .. staticmethod:: AddSubclassFactory(factory) Registers subclasses factory for use in ``XRC``. This is useful only for language bindings developers who need a way to implement subclassing in wxWidgets ports that don't support ``RTTI`` (e.g. wxPython). :param `factory`: :type `factory`: wx.xrc.XmlSubclassFactory .. method:: AttachUnknownControl(self, name, control, parent=None) Attaches an unknown control to the given panel/window/dialog. Unknown controls are used in conjunction with . :param `name`: :type `name`: string :param `control`: :type `control`: wx.Window :param `parent`: :type `parent`: wx.Window :rtype: `bool` .. method:: ClearHandlers(self) Removes all handlers and deletes them (this means that any handlers added using :meth:`AddHandler` must be allocated on the heap). .. method:: CompareVersion(self, major, minor, release, revision) 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 are equal. :param `major`: :type `major`: int :param `minor`: :type `minor`: int :param `release`: :type `release`: int :param `revision`: :type `revision`: int :rtype: `int` .. staticmethod:: FindXRCIDById(numId) Returns a string ``ID`` corresponding to the given numeric ``ID``. The string returned is such that calling :meth:`GetXRCID` with it as parameter yields `numId`. If there is no string identifier corresponding to the given numeric one, an empty string is returned. Notice that, unlike :meth:`GetXRCID` , this function is slow as it checks all of the identifiers used in ``XRC``. :param `numId`: :type `numId`: int :rtype: `string` .. versionadded:: 2.9.0 .. staticmethod:: Get() Gets the global resources object or creates one if none exists. :rtype: :ref:`wx.xrc.XmlResource` .. method:: GetDomain(self) Returns the domain (message catalog) that will be used to load translatable strings in the ``XRC``. :rtype: `string` .. method:: GetFlags(self) Returns flags, which may be a bitlist of :ref:`wx.xrc.XmlResourceFlags` enumeration values. :rtype: `int` .. method:: GetResourceNode(self, name) Returns the :ref:`wx.xml.XmlNode` containing the definition of the object with the given name or ``None``. This function recursively searches all the loaded ``XRC`` files for an object with the specified `name`. If the object is found, the :ref:`wx.xml.XmlNode` corresponding to it is returned, so this function can be used to access additional information defined in the ``XRC`` file and not used by :ref:`wx.xrc.XmlResource` itself, e.g. contents of application-specific ``XML`` tags. :param `name`: The name of the resource which must be unique for this function to work correctly, if there is more than one resource with the given name the choice of the one returned by this function is undefined. :type `name`: string :rtype: :ref:`wx.xml.XmlNode` :returns: The node corresponding to the resource with the given name or ``None``. .. method:: GetVersion(self) Returns version information (a.b.c.d = d + 256c + 2562b + 2563a). :rtype: `long` .. staticmethod:: GetXRCID(str_id, value_if_not_found=ID_NONE) Returns a numeric ``ID`` that is equivalent to the string ``ID`` used in an ``XML`` resource. If an unknown `str_id` is requested (i.e. other than ``ID_XXX`` or integer), a new record is created which associates the given string with a number. If `value_if_not_found` is ``ID_NONE`` , the number is obtained via `wx.NewId` . Otherwise `value_if_not_found` is used. Macro ``XRCID(name)`` is provided for convenient use in event tables. :param `str_id`: :type `str_id`: string :param `value_if_not_found`: :type `value_if_not_found`: int :rtype: `int` .. note:: IDs returned by XRCID() cannot be used with the ``EVT_*_RANGE`` macros, because the order in which they are assigned to symbolic `name` values is not guaranteed. .. method:: InitAllHandlers(self) Initializes handlers for all supported controls/windows. This will make the executable quite big because it forces linking against most of the wxWidgets library. .. method:: InsertHandler(self, handler) Add a new handler at the begining of the handler list. :param `handler`: :type `handler`: wx.xrc.XmlResourceHandler .. method:: Load(self, filemask) Loads resources from ``XML`` files that match given filemask. Example: :: if not wx.xml.XmlResource.Get().Load("rc/*.xrc"): wx.LogError("Couldn't load resources!") :param `filemask`: :type `filemask`: string :rtype: `bool` .. note:: If ``USE_FILESYS`` is enabled, this method understands :ref:`wx.FileSystem` URLs (see :meth:`wx.FileSystem.FindFirst` ). .. note:: If you are sure that the argument is name of single ``XRC`` file (rather than an URL or a wildcard), use :meth:`LoadFile` instead. .. seealso:: :meth:`LoadFile` , :meth:`LoadAllFiles` .. method:: LoadAllFiles(self, dirname) Loads all .xrc files from directory `dirname`. Tries to load as many files as possible; if there's an error while loading one file, it still attempts to load other files. :param `dirname`: :type `dirname`: string :rtype: `bool` .. versionadded:: 2.9.0 .. seealso:: :meth:`LoadFile` , :meth:`Load` .. method:: LoadBitmap(self, name) Loads a bitmap resource from a file. :param `name`: :type `name`: string :rtype: :ref:`wx.Bitmap` .. method:: LoadDialog(self, *args, **kw) |overload| Overloaded Implementations: **~~~** **LoadDialog** `(self, parent, name)` Loads a dialog. `parent` points to parent window (if any). :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: :ref:`wx.Dialog` **~~~** **LoadDialog** `(self, dlg, parent, name)` Loads a dialog. `parent` 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: :: dlg = wx.xml.XmlResource.Get().LoadDialog(mainFrame, "my_dialog") dlg.ShowModal() :param `dlg`: :type `dlg`: wx.Dialog :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: `bool` **~~~** .. method:: LoadFile(self, file) Simpler form of :meth:`Load` for loading a single ``XRC`` file. :param `file`: :type `file`: string :rtype: `bool` .. versionadded:: 2.9.0 .. seealso:: :meth:`Load` , :meth:`LoadAllFiles` .. method:: LoadFrame(self, *args, **kw) |overload| Overloaded Implementations: **~~~** **LoadFrame** `(self, parent, name)` Loads a frame from the resource. `parent` points to parent window (if any). :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: :ref:`wx.Frame` **~~~** **LoadFrame** `(self, frame, parent, name)` Loads the contents of a frame onto an existing :ref:`wx.Frame`. 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). :param `frame`: :type `frame`: wx.Frame :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: `bool` **~~~** .. method:: LoadFromBuffer(self, data) Load the resource from a bytes string or other data buffer compatible object. :rtype: `bool` .. method:: LoadIcon(self, name) Loads an icon resource from a file. :param `name`: :type `name`: string :rtype: :ref:`wx.Icon` .. method:: LoadMenu(self, name) Loads menu from resource. Returns ``None`` on failure. :param `name`: :type `name`: string :rtype: :ref:`wx.Menu` .. method:: LoadMenuBar(self, *args, **kw) Loads a menubar from resource. Returns ``None`` on failure. |overload| Overloaded Implementations: **~~~** **LoadMenuBar** `(self, parent, name)` :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: :ref:`wx.MenuBar` **~~~** **LoadMenuBar** `(self, name)` :param `name`: :type `name`: string :rtype: :ref:`wx.MenuBar` **~~~** .. method:: LoadObject(self, *args, **kw) Load an object from the resource specifying both the resource name and the class name. The first overload lets you load nonstandard container windows and returns ``None`` on failure. The second one lets you finish the creation of an existing instance and returns ``False`` on failure. In either case, only the resources defined at the top level of ``XRC`` files can be loaded by this function, use :meth:`LoadObjectRecursively` if you need to load an object defined deeper in the hierarchy. |overload| Overloaded Implementations: **~~~** **LoadObject** `(self, parent, name, classname)` :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :param `classname`: :type `classname`: string :rtype: :ref:`wx.Object` **~~~** **LoadObject** `(self, instance, parent, name, classname)` :param `instance`: :type `instance`: wx.Object :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :param `classname`: :type `classname`: string :rtype: `bool` **~~~** .. method:: LoadObjectRecursively(self, *args, **kw) Load an object from anywhere in the resource tree. These methods are similar to :meth:`LoadObject` but may be used to load an object from anywhere in the resource tree and not only the top level. Note that you will very rarely need to do this as in normal use the entire container window (defined at the top level) is loaded and not its individual children but this method can be useful in some particular situations. .. versionadded:: 2.9.1 |overload| Overloaded Implementations: **~~~** **LoadObjectRecursively** `(self, parent, name, classname)` :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :param `classname`: :type `classname`: string :rtype: :ref:`wx.Object` **~~~** **LoadObjectRecursively** `(self, instance, parent, name, classname)` :param `instance`: :type `instance`: wx.Object :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :param `classname`: :type `classname`: string :rtype: `bool` **~~~** .. method:: LoadPanel(self, *args, **kw) |overload| Overloaded Implementations: **~~~** **LoadPanel** `(self, parent, name)` Loads a panel. `parent` points to the parent window. :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: :ref:`wx.Panel` **~~~** **LoadPanel** `(self, panel, parent, name)` Loads a panel. `parent` points to the parent window. This form is used to finish creation of an already existing instance. :param `panel`: :type `panel`: wx.Panel :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: `bool` **~~~** .. method:: LoadToolBar(self, parent, name) Loads a toolbar. :param `parent`: :type `parent`: wx.Window :param `name`: :type `name`: string :rtype: :ref:`wx.ToolBar` .. staticmethod:: Set(res) Sets the global resources object and returns a pointer to the previous one (may be ``None``). :param `res`: :type `res`: wx.xrc.XmlResource :rtype: :ref:`wx.xrc.XmlResource` .. method:: SetDomain(self, domain) Sets the domain (message catalog) that will be used to load translatable strings in the ``XRC``. :param `domain`: :type `domain`: string .. method:: SetFlags(self, flags) Sets flags (bitlist of :ref:`wx.xrc.XmlResourceFlags` enumeration values). :param `flags`: :type `flags`: int .. method:: Unload(self, filename) This function unloads a resource previously loaded by :meth:`Load` . Returns ``True`` if the resource was successfully unloaded and ``False`` if it hasn't been found in the list of loaded resources. :param `filename`: :type `filename`: string :rtype: `bool` .. attribute:: Domain See :meth:`~wx.xrc.XmlResource.GetDomain` and :meth:`~wx.xrc.XmlResource.SetDomain` .. attribute:: Flags See :meth:`~wx.xrc.XmlResource.GetFlags` and :meth:`~wx.xrc.XmlResource.SetFlags` .. attribute:: Version See :meth:`~wx.xrc.XmlResource.GetVersion`