Add documentation of emitted events to wxScrolled documentation.

[wxWidgets.git] / interface / wx / xrc / xmlres.h

diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h
index 14d9df782ebe787023dbd79521fcbeb3166075bc..28709171bc7516671675286868b081ea6557d8dd 100644 (file)
--- a/interface/wx/xrc/xmlres.h
+++ b/interface/wx/xrc/xmlres.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxXmlResource
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxXmlResource
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -31,6 +31,9 @@ enum wxXmlResourceFlags
     The class holds XML resources from one or more .xml files, binary files or zip
     archive files.
 
     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}
     @see @ref overview_xrc, @ref overview_xrcformat
 
     @library{wxxrc}


@@ -139,6 +142,26 @@ public:
     */
     int GetFlags() const;
 
     */
     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).
     */
     /**
         Returns version information (a.b.c.d = d + 256*c + 2562*b + 2563*a).
     */


@@ -152,7 +175,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.
 
         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.
         Macro @c XRCID(name) is provided for convenient use in event tables.

+
+        @note IDs returned by XRCID() cannot be used with the <tt>EVT_*_RANGE</tt>
+              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);
 
     */
     static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
 


@@ -166,10 +194,46 @@ public:
 
     /**
         Loads resources from XML files that match given filemask.
 
     /**
         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);
 
     */
     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.
     */
     /**
         Loads a bitmap resource from a file.
     */


@@ -189,7 +253,7 @@ public:
 
         @code
           MyDialog dlg;
 
         @code
           MyDialog dlg;

-          wxTheXmlResource->LoadDialog(&dlg, mainFrame, "my_dialog");
+          wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");

           dlg.ShowModal();
         @endcode
     */
           dlg.ShowModal();
         @endcode
     */


@@ -227,6 +291,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.
         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);
     */
     wxObject* LoadObject(wxWindow* parent, const wxString& name,
                          const wxString& classname);


@@ -235,13 +303,34 @@ public:
                     const wxString& classname);
     //@}
 
                     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);
 
     /**
     */
     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);
         This form is used to finish creation of an already existing instance.
     */
     bool LoadPanel(wxPanel* panel, wxWindow* parent, const wxString& name);


@@ -275,6 +364,60 @@ public:
         hasn't been found in the list of loaded resources.
     */
     bool Unload(const wxString& filename);
         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);

 };
 
 
 };
 
 


@@ -371,7 +514,7 @@ protected:
     /**
         Creates an animation (see wxAnimation) from the filename specified in @a param.
     */
     /**
         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.
 
     /**
         Gets a bitmap.


@@ -379,6 +522,14 @@ protected:
     wxBitmap GetBitmap(const wxString& param = "bitmap",
                        const wxArtClient& defaultArtClient = wxART_OTHER,
                        wxSize size = wxDefaultSize);
     wxBitmap GetBitmap(const wxString& param = "bitmap",
                        const wxArtClient& defaultArtClient = wxART_OTHER,
                        wxSize size = wxDefaultSize);

+    /**
+        Gets a bitmap from an XmlNode.
+
+        @since 2.9.1
+    */
+    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).
 
     /**
         Gets a bool flag (1, t, yes, on, true are @true, everything else is @false).


@@ -402,6 +553,18 @@ protected:
     wxCoord GetDimension(const wxString& param, wxCoord defaultv = 0,
                          wxWindow* windowToUse = 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.
     */
     /**
         Gets a font.
     */


@@ -419,6 +582,38 @@ protected:
                    const wxArtClient& defaultArtClient = wxART_OTHER,
                    wxSize size = wxDefaultSize);
 
                    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 = wxT("imagelist"));
+

     /**
         Gets the integer value from the parameter.
     */
     /**
         Gets the integer value from the parameter.
     */


@@ -444,10 +639,17 @@ protected:
     */
     wxString GetParamValue(const wxString& param);
 
     */
     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).
     */
     /**
         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).
 
     /**
         Gets the size (may be in dialog units).


@@ -458,7 +660,7 @@ protected:
         Gets style flags from text in form "flag | flag2| flag3 |..."
         Only understands flags added with AddStyle().
     */
         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:
 
     /**
         Gets text from param and does some conversions:


@@ -485,5 +687,32 @@ protected:
         Sets common window options.
     */
     void SetupWindow(wxWindow* wnd);
         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);

 };
 
 };