Phoenix Logo

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

dlg = wx.xml.XmlResource.Get().LoadDialog(mainFrame, "my_dialog")
dlg.ShowModal()
Parameters:
Return type:

bool





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.

See also

Load , LoadAllFiles



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