X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/18e8e19b946931e18ed45fee2137257212c79fa3..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/xrc/xmlres.h diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h index a178f1a0dc..a264d2ab39 100644 --- a/interface/wx/xrc/xmlres.h +++ b/interface/wx/xrc/xmlres.h @@ -2,8 +2,7 @@ // Name: xrc/xmlres.h // Purpose: interface of wxXmlResource // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -31,7 +30,10 @@ enum wxXmlResourceFlags The class holds XML resources from one or more .xml files, binary files or zip archive files. - @see @ref overview_xrc, @ref xrc_format + Note that this is a singleton class and you'll never allocate/deallocate it. + Just use the static wxXmlResource::Get() getter. + + @see @ref overview_xrc, @ref overview_xrcformat @library{wxxrc} @category{xrc} @@ -39,7 +41,6 @@ enum wxXmlResourceFlags class wxXmlResource : public wxObject { public: - //@{ /** Constructor. @@ -55,10 +56,20 @@ public: */ wxXmlResource(const wxString& filemask, int flags = wxXRC_USE_LOCALE, - const wxString domain = wxEmptyString); + const wxString& domain = wxEmptyString); + + /** + Constructor. + + @param flags + One or more value of the ::wxXmlResourceFlags enumeration. + @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. + */ wxXmlResource(int flags = wxXRC_USE_LOCALE, - const wxString domain = wxEmptyString); - //@} + const wxString& domain = wxEmptyString); /** Destructor. @@ -77,6 +88,12 @@ public: */ void AddHandler(wxXmlResourceHandler* handler); + /** + Add a new handler at the begining of the handler list. + */ + void InsertHandler(wxXmlResourceHandler *handler); + + /** Attaches an unknown control to the given panel/window/dialog. Unknown controls are used in conjunction with \. @@ -91,6 +108,14 @@ public: */ void ClearHandlers(); + /** + 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 wxRTTI (e.g. wxPython). + */ + static void AddSubclassFactory(wxXmlSubclassFactory *factory); + + /** Compares the XRC version to the argument. @@ -99,6 +124,20 @@ public: */ int CompareVersion(int major, int minor, int release, int revision) const; + /** + Returns a string ID corresponding to the given numeric ID. + + The string returned is such that calling GetXRCID() with it as + parameter yields @a 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. + + @since 2.9.0 + */ + static wxString FindXRCIDById(int numId); + /** Gets the global resources object or creates one if none exists. */ @@ -108,7 +147,7 @@ public: Returns the domain (message catalog) that will be used to load translatable strings in the XRC. */ - wxChar* GetDomain(); + const wxString& GetDomain() const; /** Returns flags, which may be a bitlist of ::wxXmlResourceFlags @@ -116,6 +155,26 @@ public: */ int GetFlags() const; + /** + Returns the wxXmlNode containing the definition of the object with the + given name or @NULL. + + This function recursively searches all the loaded XRC files for an + object with the specified @a name. If the object is found, the + wxXmlNode corresponding to it is returned, so this function can be used + to access additional information defined in the XRC file and not used + by wxXmlResource 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. + @return + The node corresponding to the resource with the given name or @NULL. + */ + const wxXmlNode *GetResourceNode(const wxString& name) const; + /** Returns version information (a.b.c.d = d + 256*c + 2562*b + 2563*a). */ @@ -129,7 +188,12 @@ public: If @a value_if_not_found is @c wxID_NONE, the number is obtained via wxNewId(). Otherwise @a value_if_not_found is used. + Macro @c XRCID(name) is provided for convenient use in event tables. + + @note IDs returned by XRCID() cannot be used with the EVT_*_RANGE + macros, because the order in which they are assigned to symbolic @a name + values is not guaranteed. */ static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE); @@ -143,10 +207,46 @@ public: /** Loads resources from XML files that match given filemask. - This method understands VFS (see filesys.h). + + Example: + @code + if (!wxXmlResource::Get()->Load("rc/*.xrc")) + wxLogError("Couldn't load resources!"); + @endcode + + @note + If wxUSE_FILESYS is enabled, this method understands wxFileSystem URLs + (see wxFileSystem::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 LoadFile(), LoadAllFiles() */ bool Load(const wxString& filemask); + /** + Simpler form of Load() for loading a single XRC file. + + @since 2.9.0 + + @see Load(), LoadAllFiles() + */ + bool LoadFile(const wxFileName& file); + + /** + Loads all .xrc files from directory @a 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. + + @since 2.9.0 + + @see LoadFile(), Load() + */ + bool LoadAllFiles(const wxString& dirname); + /** Loads a bitmap resource from a file. */ @@ -166,14 +266,23 @@ public: @code MyDialog dlg; - wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog"); + wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog"); dlg.ShowModal(); @endcode */ bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name); /** - Loads a frame. + Loads a frame from the resource. @a parent points to parent window (if any). + */ + wxFrame *LoadFrame(wxWindow* parent, const wxString& name); + + /** + Loads the contents of a frame onto an existing wxFrame. + + 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). */ bool LoadFrame(wxFrame* frame, wxWindow* parent, const wxString& name); @@ -204,6 +313,10 @@ public: The first overload lets you load nonstandard container windows and returns @NULL 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. */ wxObject* LoadObject(wxWindow* parent, const wxString& name, const wxString& classname); @@ -212,13 +325,34 @@ public: const wxString& classname); //@} + //@{ + /** + 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. + + @since 2.9.1 + */ + wxObject* LoadObjectRecursively(wxWindow* parent, + const wxString& name, + const wxString& classname); + bool LoadObjectRecursively(wxObject* instance, wxWindow* parent, + const wxString& name, + const wxString& classname); + //@} + /** - Loads a panel. @a panel points to parent window (if any). + Loads a panel. @a parent points to the parent window. */ wxPanel* LoadPanel(wxWindow* parent, const wxString& name); /** - Loads a panel. @a panel points to parent window (if any). + Loads a panel. @a parent points to the parent window. This form is used to finish creation of an already existing instance. */ bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name); @@ -238,7 +372,7 @@ public: Sets the domain (message catalog) that will be used to load translatable strings in the XRC. */ - wxChar* SetDomain(const wxChar* domain); + void SetDomain(const wxString& domain); /** Sets flags (bitlist of ::wxXmlResourceFlags enumeration values). @@ -252,6 +386,60 @@ public: hasn't been found in the list of loaded resources. */ bool Unload(const wxString& filename); + +protected: + /** + Reports error in XRC resources to the user. + + Any errors in XRC input files should be reported using this method + (or its wxXmlResourceHandler::ReportError() equivalent). Unlike + wxLogError(), this method presents the error to the user in a more + usable form. In particular, the output is compiler-like and contains + information about the exact location of the error. + + @param context XML node the error occurred in or relates to. This can + be @NULL, but should be the most specific node possible, + as its line number is what is reported to the user. + @param message Text of the error message. This string should always + be in English (i.e. not wrapped in _()). It shouldn't + be a sentence -- it should start with lower-case letter + and shouldn't have a trailing period or exclamation + point. + + @since 2.9.0 + + @see wxXmlResourceHandler::ReportError(), DoReportError() + */ + void ReportError(const wxXmlNode *context, const wxString& message); + + /** + Implementation of XRC resources errors reporting. + + This method is called by ReportError() and shouldn't be called + directly; use ReportError() or wxXmlResourceHandler::ReportError() + to log errors. + + Default implementation uses wxLogError(). + + @param xrcFile File the error occurred in or empty string if it + couldn't be determined. + @param position XML node where the error occurred or @NULL if it + couldn't be determined. + @param message Text of the error message. See ReportError() + documentation for details of the string's format. + + @note + You may override this method in a derived class to customize errors + reporting. If you do so, you'll need to either use the derived class + in all your code or call wxXmlResource::Set() to change the global + wxXmlResource instance to your class. + + @since 2.9.0 + + @see ReportError() + */ + virtual void DoReportError(const wxString& xrcFile, const wxXmlNode *position, + const wxString& message); }; @@ -281,15 +469,21 @@ public: virtual ~wxXmlResourceHandler(); /** - Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags - understood by this handler. + Creates an object (menu, dialog, control, ...) from an XML node. + Should check for validity. @a parent is a higher-level object + (usually window, dialog or panel) that is often necessary to + create the resource. + + If @b instance is non-@NULL it should not create a new instance via + 'new' but should rather use this one, and call its Create method. */ - void AddStyle(const wxString& name, int value); + wxObject* CreateResource(wxXmlNode* node, wxObject* parent, + wxObject* instance); /** - Add styles common to all wxWindow-derived classes. + Called from CreateResource after variables were filled. */ - void AddWindowStyles(); + virtual wxObject* DoCreateResource() = 0; /** Returns @true if it understands this node and can create @@ -301,7 +495,26 @@ public: at the time CanHandle() is called and it is only safe to operate on node directly or to call IsOfClass(). */ - bool CanHandle(wxXmlNode* node); + virtual bool CanHandle(wxXmlNode* node) = 0; + + /** + Sets the parent resource. + */ + void SetParentResource(wxXmlResource* res); + + +protected: + + /** + Add a style flag (e.g. @c wxMB_DOCKABLE) to the list of flags + understood by this handler. + */ + void AddStyle(const wxString& name, int value); + + /** + Add styles common to all wxWindow-derived classes. + */ + void AddWindowStyles(); /** Creates children. @@ -321,31 +534,24 @@ public: wxObject* instance = NULL); /** - Creates an object (menu, dialog, control, ...) from an XML node. - Should check for validity. @a parent is a higher-level object - (usually window, dialog or panel) that is often necessary to - create the resource. - - If @b instance is non-@NULL it should not create a new instance via 'new' - but should rather use this one, and call its Create method. + Creates an animation (see wxAnimation) from the filename specified in @a param. */ - wxObject* CreateResource(wxXmlNode* node, wxObject* parent, - wxObject* instance); + wxAnimation* GetAnimation(const wxString& param = "animation"); /** - Called from CreateResource after variables were filled. + Gets a bitmap. */ - wxObject* DoCreateResource(); - + wxBitmap GetBitmap(const wxString& param = "bitmap", + const wxArtClient& defaultArtClient = wxART_OTHER, + wxSize size = wxDefaultSize); /** - Creates an animation (see wxAnimation) from the filename specified in @a param. - */ - wxAnimation GetAnimation(const wxString& param = wxT("animation")); + Gets a bitmap from an XmlNode. - /** - Gets a bitmap. + @since 2.9.1 */ - wxBitmap GetBitmap(const wxString& param = wxT("bitmap"), wxSize size = wxDefaultSize); + wxBitmap GetBitmap(const wxXmlNode* node, + const wxArtClient& defaultArtClient = wxART_OTHER, + wxSize size = wxDefaultSize); /** Gets a bool flag (1, t, yes, on, true are @true, everything else is @false). @@ -361,17 +567,30 @@ public: /** Returns the current file system. */ - wxFileSystem GetCurFileSystem(); + wxFileSystem& GetCurFileSystem(); /** Gets a dimension (may be in dialog units). */ - wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0); + wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0, + wxWindow* windowToUse = 0); + + /** + Gets a direction. + + If the given @a param is not present or has empty value, @a dir is + returned by default. Otherwise the value of the parameter is parsed and + a warning is generated if it's not one of @c wxLEFT, @c wxTOP, @c + wxRIGHT or @c wxBOTTOM. + + @since 2.9.3 + */ + wxDirection GetDirection(const wxString& param, wxDirection dir = wxLEFT); /** Gets a font. */ - wxFont GetFont(); + wxFont GetFont(const wxString& param = "font"); /** Returns the XRCID. @@ -381,13 +600,52 @@ public: /** Returns an icon. */ - wxIcon GetIcon(const wxString& param = wxT("icon"), wxSize size = wxDefaultSize); + wxIcon GetIcon(const wxString& param = "icon", + const wxArtClient& defaultArtClient = wxART_OTHER, + wxSize size = wxDefaultSize); + + /** + Gets an icon from an XmlNode. + + @since 2.9.1 + */ + wxIcon GetIcon(const wxXmlNode* node, + const wxArtClient& defaultArtClient = wxART_OTHER, + wxSize size = wxDefaultSize); + + /** + Returns an icon bundle. + + @note + Bundles can be loaded either with stock IDs or from files that contain + more than one image (e.g. Windows icon files). If a file contains only + single image, a bundle with only one icon will be created. + + @since 2.9.0 + */ + wxIconBundle GetIconBundle(const wxString& param, + const wxArtClient& defaultArtClient = wxART_OTHER); + + /** + Creates an image list from the @a param markup data. + + @return + The new instance of wxImageList or @NULL if no data is found. + + @since 2.9.1 + */ + wxImageList *GetImageList(const wxString& param = "imagelist"); /** Gets the integer value from the parameter. */ long GetLong(const wxString& param, long defaultv = 0); + /** + Gets a float value from the parameter. + */ + float GetFloat(const wxString& param, float defaultv = 0); + /** Returns the resource name. */ @@ -408,21 +666,28 @@ public: */ wxString GetParamValue(const wxString& param); + /** + Returns the node parameter value. + + @since 2.9.1 + */ + wxString GetParamValue(const wxXmlNode* node); + /** Gets the position (may be in dialog units). */ - wxPoint GetPosition(const wxString& param = wxT("pos")); + wxPoint GetPosition(const wxString& param = "pos"); /** Gets the size (may be in dialog units). */ - wxSize GetSize(const wxString& param = wxT("size")); + wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0); /** Gets style flags from text in form "flag | flag2| flag3 |..." Only understands flags added with AddStyle(). */ - int GetStyle(const wxString& param = wxT("style"), int defaults = 0); + int GetStyle(const wxString& param = "style", int defaults = 0); /** Gets text from param and does some conversions: @@ -431,7 +696,7 @@ public: translation because of XML syntax) - calls wxGetTranslations (unless disabled in wxXmlResource) */ - wxString GetText(const wxString& param); + wxString GetText(const wxString& param, bool translate = true); /** Check to see if a parameter exists. @@ -446,13 +711,85 @@ public: bool IsOfClass(wxXmlNode* node, const wxString& classname); /** - Sets the parent resource. + Sets common window options. */ - void SetParentResource(wxXmlResource* res); + void SetupWindow(wxWindow* wnd); /** - Sets common window options. + Reports error in XRC resources to the user. + + See wxXmlResource::ReportError() for more information. + + @since 2.9.0 + */ + void ReportError(wxXmlNode *context, const wxString& message); + + /** + Like ReportError(wxXmlNode*, const wxString&), but uses the node + of currently processed object (m_node) as the context. + + @since 2.9.0 + */ + void ReportError(const wxString& message); + + /** + Like ReportError(wxXmlNode*, const wxString&), but uses the node + of parameter @a param of the currently processed object as the context. + This is convenience function for reporting errors in particular + parameters. + + @since 2.9.0 + */ + void ReportParamError(const wxString& param, const wxString& message); + + + /** + After CreateResource has been called this will return the current + wxXmlResource object. + + @since 2.9.5 */ - void SetupWindow(wxWindow* wnd); + wxXmlResource* GetResource() const; + + /** + After CreateResource has been called this will return the XML node + being processed. + + @since 2.9.5 + */ + wxXmlNode* GetNode() const; + + /** + After CreateResource has been called this will return the class name of + the XML resource node being processed. + + @since 2.9.5 + */ + wxString GetClass() const; + + /** + After CreateResource has been called this will return the current + item's parent, if any. + + @since 2.9.5 + */ + wxObject* GetParent() const; + + /** + After CreateResource has been called this will return the instance that + the XML resource content should be created upon, if it has already been + created. If @NULL then the handler should create the object itself. + + @since 2.9.5 + */ + wxObject* GetInstance() const; + + /** + After CreateResource has been called this will return the item's parent + as a wxWindow. + + @since 2.9.5 + */ + wxWindow* GetParentAsWindow() const; };