Add test for absence of events from wxSpinCtrlDouble ctor.

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

diff --git a/interface/wx/xrc/xmlres.h b/interface/wx/xrc/xmlres.h
index 75b8820a00d45b851bd7071b1fe1b6f006a35ecf..a264d2ab39d05a2ca60568cf307fda6762f6b55a 100644 (file)
--- 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
 // Name:        xrc/xmlres.h
 // Purpose:     interface of wxXmlResource
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

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


@@ -89,6 +88,12 @@ public:
     */
     void AddHandler(wxXmlResourceHandler* handler);
 
     */
     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 \<object class="unknown"\>.
     /**
         Attaches an unknown control to the given panel/window/dialog.
         Unknown controls are used in conjunction with \<object class="unknown"\>.


@@ -103,6 +108,14 @@ public:
     */
     void ClearHandlers();
 
     */
     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.
 
     /**
         Compares the XRC version to the argument.
 


@@ -142,6 +155,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).
     */


@@ -155,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.
 
         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);
 


@@ -176,10 +214,39 @@ public:
                 wxLogError("Couldn't load resources!");
         @endcode
 
                 wxLogError("Couldn't load resources!");
         @endcode
 

-        This method understands VFS (see wxFileSystem::FindFirst).
+        @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.
     */


@@ -206,7 +273,16 @@ public:
     bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 
     /**
     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);
     */
     bool LoadFrame(wxFrame* frame, wxWindow* parent,
                    const wxString& name);


@@ -237,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.
         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);


@@ -245,13 +325,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);


@@ -285,6 +386,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);

 };
 
 
 };
 
 


@@ -381,7 +536,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.


@@ -389,6 +544,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).


@@ -412,6 +575,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.
     */


@@ -429,11 +604,48 @@ 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 = "imagelist");
+

     /**
         Gets the integer value from the parameter.
     */
     long GetLong(const wxString& param, long defaultv = 0);
 
     /**
         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.
     */
     /**
         Returns the resource name.
     */


@@ -454,10 +666,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).


@@ -468,7 +687,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:


@@ -495,5 +714,82 @@ 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);
+
+
+    /**
+       After CreateResource has been called this will return the current
+       wxXmlResource object.
+       
+       @since 2.9.5
+    */
+    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;    

 };
 
 };