]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/xrc/xmlres.h
don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / xrc / xmlres.h
index c63738d48b850632b478d47bd8079e2810123052..c07f44c0171be55b56f1bfde0c9738d89ce97371 100644 (file)
@@ -6,6 +6,23 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Flags which can be used with wxXmlResource::wxXmlResource.
+*/
+enum wxXmlResourceFlags
+{
+    /** Translatable strings will be translated via _(). */
+    wxXRC_USE_LOCALE     = 1,
+
+    /** Subclass property of object nodes will be ignored (useful for previews in XRC editors). */
+    wxXRC_NO_SUBCLASSING = 2,
+
+    /** Prevent the XRC files from being reloaded from disk in case they have been modified there
+        since being last loaded (may slightly speed up loading them). */
+    wxXRC_NO_RELOADING   = 4
+};
+
+
 /**
     @class wxXmlResource
 
     The class holds XML resources from one or more .xml files, binary files or zip
     archive files.
 
-    See @ref overview_xrcoverview "XML-based resource system overview" for details.
+    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}
 class wxXmlResource : public wxObject
 {
 public:
-    //@{
     /**
         Constructor.
-        
+
+        @param filemask
+            The XRC file, archive file, or wildcard specification that will be
+            used to load all resource files inside a zip archive.
         @param flags
-            wxXRC_USE_LOCALE: translatable strings will be translated via _().
-            wxXRC_NO_SUBCLASSING: subclass property of object nodes will be ignored
-            (useful for previews in XRC editors). wxXRC_NO_RELOADING will prevent the
-            XRC files from being reloaded from disk in case they have been modified
-        there
-            since being last loaded (may slightly speed up loading them).
+            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.
+            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(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.
     */
-    ~wxXmlResource();
+    virtual ~wxXmlResource();
 
     /**
-        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
-        wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler. The XML resource compiler
-        (wxxrc) can create include file that contains initialization code for
-        all controls used within the resource. Note that this handler should be
-        allocated on the heap, since it will be delete by
-        ClearHandlers() later.
+        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 wxTextCtrlXmlHandler, wxHtmlWindowXmlHandler.
+
+        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.
     */
     void AddHandler(wxXmlResourceHandler* handler);
 
     /**
         Attaches an unknown control to the given panel/window/dialog.
-        Unknown controls are used in conjunction with object class="unknown".
+        Unknown controls are used in conjunction with \<object class="unknown"\>.
     */
     bool AttachUnknownControl(const wxString& name,
                               wxWindow* control,
                               wxWindow* parent = NULL);
 
     /**
-        Removes all handlers and deletes them (this means that any handlers added using
-        AddHandler() must be allocated on the heap).
+        Removes all handlers and deletes them (this means that any handlers
+        added using AddHandler() must be allocated on the heap).
     */
     void ClearHandlers();
 
     /**
-        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 equal.
+        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.
     */
-    int CompareVersion(int major, int minor, int release,
-                       int revision) const;
+    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.
     */
-    wxXmlResource* Get();
+    static wxXmlResource* Get();
 
     /**
         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 wxXRC_USE_LOCALE and
-        wxXRC_NO_SUBCLASSING.
+        Returns flags, which may be a bitlist of ::wxXmlResourceFlags
+        enumeration values.
     */
-    int GetFlags();
+    int GetFlags() const;
 
     /**
-        Returns version information (a.b.c.d = d+ 256*c + 256@c 2*b + 256@c 3*a).
+        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).
     */
     long GetVersion() const;
 
     /**
-        Returns a numeric ID that is equivalent to the string ID used in an XML
-        resource. If an unknown @a str_id is requested (i.e. other than wxID_XXX
-        or integer), a new record is created which associates the given string with
-        a number. If @a value_if_not_found is @c wxID_NONE, the number is obtained via
+        Returns a numeric ID that is equivalent to the string ID used in an XML resource.
+
+        If an unknown @a str_id is requested (i.e. other than wxID_XXX or integer),
+        a new record is created which associates the given string with a number.
+
+        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.
     */
-#define int GetXRCID(const wxString& str_id, int value_if_not_found = -2)     /* implementation is private */
+    static int GetXRCID(const wxString& str_id, int value_if_not_found = wxID_NONE);
 
     /**
-        Initializes handlers for all supported controls/windows. This will
-        make the executable quite big because it forces linking against
+        Initializes handlers for all supported controls/windows.
+
+        This will make the executable quite big because it forces linking against
         most of the wxWidgets library.
     */
     void InitAllHandlers();
 
     /**
         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.
     */
     wxBitmap LoadBitmap(const wxString& name);
 
-    //@{
     /**
-        Loads a dialog. @a dlg points to parent window (if any).
+        Loads a dialog. @a parent points to parent window (if any).
+    */
+    wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
+
+    /**
+        Loads a dialog. @a 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).
+        reason for this is that you may want to use derived class with a new event table).
         Example:
+
+        @code
+          MyDialog dlg;
+          wxXmlResource::Get()->LoadDialog(&dlg, mainFrame, "my_dialog");
+          dlg.ShowModal();
+        @endcode
     */
-    wxDialog* LoadDialog(wxWindow* parent, const wxString& name);
-    bool LoadDialog(wxDialog* dlg, wxWindow* parent,
-                    const wxString& name);
-    //@}
+    bool LoadDialog(wxDialog* dlg, wxWindow* parent, const wxString& name);
 
     /**
         Loads a frame.
@@ -175,9 +282,9 @@ public:
     /**
         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 @c
-        @NULL
-        on failure. The second one lets you finish the creation of an existing
+
+        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.
     */
     wxObject* LoadObject(wxWindow* parent, const wxString& name,
@@ -187,15 +294,16 @@ public:
                     const wxString& classname);
     //@}
 
-    //@{
     /**
-        Loads a panel. @a panel points to parent window (if any). This form
-        is used to finish creation of an already existing instance.
+        Loads a panel. @a parent points to the parent window.
     */
     wxPanel* LoadPanel(wxWindow* parent, const wxString& name);
-    bool LoadPanel(wxPanel* panel, wxWindow* parent,
-                   const wxString& name);
-    //@}
+
+    /**
+        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);
 
     /**
         Loads a toolbar.
@@ -203,30 +311,83 @@ public:
     wxToolBar* LoadToolBar(wxWindow* parent, const wxString& name);
 
     /**
-        Sets the global resources object and returns a pointer to the previous one (may
-        be @NULL).
+        Sets the global resources object and returns a pointer to the previous one
+        (may be @NULL).
     */
-    wxXmlResource* Set(wxXmlResource* res);
+    static wxXmlResource* Set(wxXmlResource* res);
 
     /**
         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 wxXRC_USE_LOCALE and wxXRC_NO_SUBCLASSING).
+        Sets flags (bitlist of ::wxXmlResourceFlags enumeration values).
     */
     void SetFlags(int flags);
 
     /**
-        This function unloads a resource previously loaded by
-        Load().
+        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.
+        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);
 };
 
 
@@ -237,7 +398,7 @@ public:
     wxXmlResourceHandler is an abstract base class for resource handlers
     capable of creating a control from an XML node.
 
-    See @ref overview_xrcoverview "XML-based resource system overview" for details.
+    See @ref overview_xrc for details.
 
     @library{wxxrc}
     @category{xrc}
@@ -253,24 +414,55 @@ public:
     /**
         Destructor.
     */
-    ~wxXmlResourceHandler();
+    virtual ~wxXmlResourceHandler();
 
     /**
-        Add a style flag (e.g. 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
         a resource from it, @false otherwise.
+
+        @note
+        You must not call any wxXmlResourceHandler methods except IsOfClass()
+        from this method! The instance is not yet initialized with node data
+        at the time CanHandle() is called and it is only safe to operate on
+        node directly or to call IsOfClass().
+    */
+    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.
     */
-    bool CanHandle(wxXmlNode* node);
+    void AddStyle(const wxString& name, int value);
+
+    /**
+        Add styles common to all wxWindow-derived classes.
+    */
+    void AddWindowStyles();
 
     /**
         Creates children.
@@ -290,60 +482,43 @@ 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.
-    */
-    wxObject* DoCreateResource();
-
-    /**
-        )
-        Creates a animation() from the filename specified in @e param.
-    */
-    wxAnimation GetAnimation();
-
-    /**
-        , @b wxSize@e size = wxDefaultSize)
         Gets a bitmap.
     */
-    wxBitmap GetBitmap();
+    wxBitmap GetBitmap(const wxString& param = "bitmap",
+                       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).
     */
     bool GetBool(const wxString& param, bool defaultv = false);
 
     /**
-        Gets colour in HTML syntax (#RRGGBB).
+        Gets colour in HTML syntax (\#RRGGBB).
     */
     wxColour GetColour(const wxString& param,
-                   const wxColour& default = wxNullColour);
+                       const wxColour& defaultColour = wxNullColour);
 
     /**
         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 font.
     */
-    wxFont GetFont();
+    wxFont GetFont(const wxString& param = "font");
 
     /**
         Returns the XRCID.
@@ -351,10 +526,24 @@ public:
     int GetID();
 
     /**
-        , @b wxSize@e size = wxDefaultSize)
         Returns an icon.
     */
-    wxIcon GetIcon();
+    wxIcon GetIcon(const wxString& param = "icon",
+                   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.
@@ -382,32 +571,29 @@ public:
     wxString GetParamValue(const wxString& param);
 
     /**
-        )
         Gets the position (may be in dialog units).
     */
-    wxPoint GetPosition();
+    wxPoint GetPosition(const wxString& param = "pos");
 
     /**
-        )
         Gets the size (may be in dialog units).
     */
-    wxSize GetSize();
+    wxSize GetSize(const wxString& param = "size", wxWindow* windowToUse = 0);
 
     /**
-        , @b int@e defaults = 0)
         Gets style flags from text in form "flag | flag2| flag3 |..."
-        Only understands flags added with AddStyle.
+        Only understands flags added with AddStyle().
     */
-    int GetStyle();
+    int GetStyle(const wxString& param = "style", int defaults = 0);
 
     /**
         Gets text from param and does some conversions:
-         replaces \n, \r, \t by respective characters (according to C syntax)
-         replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
-        translation because of XML syntax)
-         calls wxGetTranslations (unless disabled in wxXmlResource)
+        - replaces \\n, \\r, \\t by respective characters (according to C syntax)
+        - replaces @c $ by @c  and @c $$ by @c $ (needed for @c _File to @c File
+          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.
@@ -415,20 +601,42 @@ public:
     bool HasParam(const wxString& param);
 
     /**
-        Convenience function. Returns @true if the node has a property class equal to
-        classname,
+        Convenience function.
+        Returns @true if the node has a property class equal to classname,
         e.g. object class="wxDialog".
     */
     bool IsOfClass(wxXmlNode* node, const wxString& classname);
 
-    /**
-        Sets the parent resource.
-    */
-    void SetParentResource(wxXmlResource* res);
-
     /**
         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);
 };