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 wx.xrc.XmlResource.Get getter.

See also

XML Based Resource System , XRC File Format


class_hierarchy Class Hierarchy

Inheritance diagram for class XmlResource:

method_summary Methods Summary

__init__

Constructor.

AddHandler

Initializes only a specific handler (or custom handler).

AddSubclassFactory

Registers subclasses factory for use in XRC.

AttachUnknownControl

Attaches an unknown control to the given panel/window/dialog.

ClearHandlers

Removes all handlers and deletes them (this means that any handlers added using AddHandler must be allocated on the heap).

CompareVersion

Compares the XRC version to the argument.

FindXRCIDById

Returns a string ID corresponding to the given numeric ID.

Get

Gets the global resources object or creates one if none exists.

GetDomain

Returns the domain (message catalog) that will be used to load translatable strings in the XRC.

GetFlags

Returns flags, which may be a bitlist of wx.xrc.XmlResourceFlags enumeration values.

GetResourceNode

Returns the wx.xml.XmlNode containing the definition of the object with the given name or None.

GetVersion

Returns version information (a.b.c.d = d + 256c + 2562b + 2563a).

GetXRCID

Returns a numeric ID that is equivalent to the string ID used in an XML resource.

InitAllHandlers

Initializes handlers for all supported controls/windows.

InsertHandler

Add a new handler at the beginning of the handler list.

Load

Loads resources from XML files that match given filemask.

LoadAllFiles

Loads all .xrc files from directory dirname.

LoadBitmap

Loads a bitmap resource from a file.

LoadDialog

Loads a dialog.

LoadDocument

Load resources from the XML document containing them.

LoadFile

Simpler form of Load for loading a single XRC file.

LoadFrame

Loads a frame from the resource.

LoadFromBuffer

Load the resource from a bytes string or other data buffer compatible object.

LoadIcon

Loads an icon resource from a file.

LoadMenu

Loads menu from resource.

LoadMenuBar

Loads a menubar from resource.

LoadObject

Load an object from the resource specifying both the resource name and the class name.

LoadObjectRecursively

Load an object from anywhere in the resource tree.

LoadPanel

Loads a panel.

LoadToolBar

Loads a toolbar.

Set

Sets the global resources object and returns a pointer to the previous one (may be None).

SetDomain

Sets the domain (message catalog) that will be used to load translatable strings in the XRC.

SetFlags

Sets flags (bitlist of wx.xrc.XmlResourceFlags enumeration values).

Unload

This function unloads a resource previously loaded by Load .


property_summary Properties Summary

Domain

See GetDomain and SetDomain

Flags

See GetFlags and SetFlags

Version

See 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.


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self, filemask, flags=XRC_USE_LOCALE, domain=””)

Constructor.

Parameters
  • filemask (string) – The XRC file, archive file, or wildcard specification that will be used to load all resource files inside a zip archive.

  • flags (int) – One or more value of the wx.xrc.XmlResourceFlags enumeration.

  • domain (string) – 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.



__init__ (self, flags=XRC_USE_LOCALE, domain=””)

Constructor.

Parameters
  • flags (int) – One or more value of the wx.xrc.XmlResourceFlags enumeration.

  • domain (string) – 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.





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 ClearHandlers later.

Parameters

handler (wx.xrc.XmlResourceHandler) –



static 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).

Parameters

factory (wx.xrc.XmlSubclassFactory) –



AttachUnknownControl(self, name, control, parent=None)

Attaches an unknown control to the given panel/window/dialog.

Unknown controls are used in conjunction with <object class=”unknown”>.

Parameters
Return type

bool



ClearHandlers(self)

Removes all handlers and deletes them (this means that any handlers added using AddHandler must be allocated on the heap).



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.

Parameters
  • major (int) –

  • minor (int) –

  • release (int) –

  • revision (int) –

Return type

int



static FindXRCIDById(numId)

Returns a string ID corresponding to the given numeric ID.

The string returned is such that calling 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 GetXRCID , this function is slow as it checks all of the identifiers used in XRC.

Parameters

numId (int) –

Return type

string

New in version 2.9.0.



static Get()

Gets the global resources object or creates one if none exists.

Return type

wx.xrc.XmlResource



GetDomain(self)

Returns the domain (message catalog) that will be used to load translatable strings in the XRC.

Return type

string



GetFlags(self)

Returns flags, which may be a bitlist of wx.xrc.XmlResourceFlags enumeration values.

Return type

int



GetResourceNode(self, name)

Returns the 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 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 wx.xrc.XmlResource itself, e.g. contents of application-specific XML tags.

Parameters

name (string) – 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.

Return type

wx.xml.XmlNode

Returns

The node corresponding to the resource with the given name or None.



GetVersion(self)

Returns version information (a.b.c.d = d + 256c + 2562b + 2563a).

Return type

long



static 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.

Parameters
  • str_id (string) –

  • value_if_not_found (int) –

Return type

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.



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.



InsertHandler(self, handler)

Add a new handler at the beginning of the handler list.

Parameters

handler (wx.xrc.XmlResourceHandler) –



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!")
Parameters

filemask (string) –

Return type

bool

Note

If USE_FILESYS is enabled, this method understands wx.FileSystem URLs (see 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 LoadFile instead.

See also

LoadFile , LoadAllFiles



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.

Parameters

dirname (string) –

Return type

bool

New in version 2.9.0.

See also

LoadFile , Load



LoadBitmap(self, name)

Loads a bitmap resource from a file.

Parameters

name (string) –

Return type

wx.Bitmap



LoadDialog(self, *args, **kw)

overload Overloaded Implementations:



LoadDialog (self, parent, name)

Loads a dialog.

parent points to parent window (if any).

Parameters
Return type

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:

# Without a class
dlg = wx.Dialog()
wx.xml.XmlResource.Get().LoadDialog(dlg, mainFrame, "my_dialog")
dlg.ShowModal()

# Or, as a class
class MyDialog(wx.Dialog):
    def __init__(self, parent):
        super().__init__()
        wx.xml.XmlResource.Get().LoadDialog(self, parent, "my_dialog")
Parameters
Return type

bool





LoadDocument(self, doc, name="")

Load resources from the XML document containing them.

This can be useful when XRC contents comes from some place other than a file or, more generally, an URL, as it can still be read into a MemoryInputStream and then wx.xml.XmlDocument can be created from this stream and used with this function.

For example:

xrc_data = ... # Retrieve it from wherever.
xmlDoc = wx.xml.XmlDocument(io.BytesIO(xrc_data))
if not xmlDoc.IsOk():
    ... handle invalid XML here ...
    return

if not wx.XmlResource.Get().LoadDocument(xmlDoc):
    ... handle invalid XRC here ...
    return

... use the just loaded XRC as usual ...
Parameters
  • doc (wx.xml.XmlDocument) – A valid, i.e. non-null, document pointer ownership of which is passed to wx.xrc.XmlResource, i.e. this pointer can’t be used after this function rteturns.

  • name (string) – The name argument is optional, but may be provided if you plan to call Unload later. It doesn’t need to be an existing file or even conform to the usual form of file names as it is not interpreted in any way by wx.xrc.XmlResource, but it should be unique among the other documents and file names used if specified.

Return type

bool

Returns

True on success, False if the document couldn’t be loaded (note that doc is still destroyed in this case to avoid memory leaks).

New in version 4.1/wxWidgets-3.1.6.

See also

Load , LoadFile



LoadFile(self, file)

Simpler form of Load for loading a single XRC file.

Parameters

file (string) –

Return type

bool

New in version 2.9.0.



LoadFrame(self, *args, **kw)

overload Overloaded Implementations:



LoadFrame (self, parent, name)

Loads a frame from the resource.

parent points to parent window (if any).

Parameters
Return type

wx.Frame



LoadFrame (self, frame, parent, name)

Loads the contents of a frame onto an existing 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).

Parameters
Return type

bool





LoadFromBuffer(self, data)

Load the resource from a bytes string or other data buffer compatible object.

Return type

bool



LoadIcon(self, name)

Loads an icon resource from a file.

Parameters

name (string) –

Return type

wx.Icon



LoadMenu(self, name)

Loads menu from resource.

Returns None on failure.

Parameters

name (string) –

Return type

wx.Menu



LoadMenuBar(self, *args, **kw)

Loads a menubar from resource.

Returns None on failure.

overload Overloaded Implementations:



LoadMenuBar (self, parent, name)

Parameters
Return type

wx.MenuBar



LoadMenuBar (self, name)

Parameters

name (string) –

Return type

wx.MenuBar





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 LoadObjectRecursively if you need to load an object defined deeper in the hierarchy.

overload Overloaded Implementations:



LoadObject (self, parent, name, classname)

Parameters
  • parent (wx.Window) –

  • name (string) –

  • classname (string) –

Return type

wx.Object



LoadObject (self, instance, parent, name, classname)

Parameters
  • instance (wx.Object) –

  • parent (wx.Window) –

  • name (string) –

  • classname (string) –

Return type

bool





LoadObjectRecursively(self, *args, **kw)

Load an object from anywhere in the resource tree.

These methods are similar to 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.

New in version 2.9.1.

overload Overloaded Implementations:



LoadObjectRecursively (self, parent, name, classname)

Parameters
  • parent (wx.Window) –

  • name (string) –

  • classname (string) –

Return type

wx.Object



LoadObjectRecursively (self, instance, parent, name, classname)

Parameters
  • instance (wx.Object) –

  • parent (wx.Window) –

  • name (string) –

  • classname (string) –

Return type

bool





LoadPanel(self, *args, **kw)

overload Overloaded Implementations:



LoadPanel (self, parent, name)

Loads a panel.

parent points to the parent window.

Parameters
Return type

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.

Parameters
Return type

bool





LoadToolBar(self, parent, name)

Loads a toolbar.

Parameters
Return type

wx.ToolBar



static Set(res)

Sets the global resources object and returns a pointer to the previous one (may be None).

Parameters

res (wx.xrc.XmlResource) –

Return type

wx.xrc.XmlResource



SetDomain(self, domain)

Sets the domain (message catalog) that will be used to load translatable strings in the XRC.

Parameters

domain (string) –



SetFlags(self, flags)

Sets flags (bitlist of wx.xrc.XmlResourceFlags enumeration values).

Parameters

flags (int) –



Unload(self, filename)

This function unloads a resource previously loaded by Load .

Returns True if the resource was successfully unloaded and False if it hasn’t been found in the list of loaded resources.

Parameters

filename (string) –

Return type

bool


Properties

Domain

See GetDomain and SetDomain



Flags

See GetFlags and SetFlags



Version

See GetVersion