X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cfbe561401380c3308f92c02b1b34f05d067a18e..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/xrc/xmlres.h diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h index 93c10b126a..c07f44c017 100644 --- a/interface/wx/xrc/xmlres.h +++ b/interface/wx/xrc/xmlres.h @@ -31,6 +31,9 @@ enum wxXmlResourceFlags 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 wxXmlResource::Get() getter. + @see @ref overview_xrc, @ref overview_xrcformat @library{wxxrc} @@ -120,7 +123,7 @@ public: @since 2.9.0 */ - static wxString wxXmlResource::FindXRCIDById(int numId); + static wxString FindXRCIDById(int numId); /** Gets the global resources object or creates one if none exists. @@ -139,6 +142,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). */ @@ -166,10 +189,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. */ @@ -189,7 +248,7 @@ public: @code MyDialog dlg; - wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog"); + wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog"); dlg.ShowModal(); @endcode */ @@ -236,12 +295,12 @@ public: //@} /** - 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); @@ -275,6 +334,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(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, wxXmlNode *position, + const wxString& message); }; @@ -371,7 +484,7 @@ protected: /** Creates an animation (see wxAnimation) from the filename specified in @a param. */ - wxAnimation GetAnimation(const wxString& param = wxT("animation")); + wxAnimation GetAnimation(const wxString& param = "animation"); /** Gets a bitmap. @@ -419,6 +532,19 @@ protected: 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); + /** Gets the integer value from the parameter. */ @@ -447,7 +573,7 @@ protected: /** 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). @@ -458,7 +584,7 @@ protected: 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: @@ -485,5 +611,32 @@ protected: Sets common window options. */ void SetupWindow(wxWindow* wnd); + + /** + 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); };