synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / msw / ole / automtn.h

diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h
index 397703cbe8cb18e5c75e04aadf38e9eff064736f..916bc1b80dce8ae267bbec0bcfeedb6df7808800 100644 (file)
--- a/interface/wx/msw/ole/automtn.h
+++ b/interface/wx/msw/ole/automtn.h
@@ -6,6 +6,43 @@
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    Automation object creation flags.
+
+    These flags can be used with wxAutomationObject::GetInstance().
+
+    @since 2.9.2
+*/
+enum wxAutomationInstanceFlags
+{
+    /**
+        Only use the existing instance, never create a new one.
+
+        This flag can be used to forbid the creation of a new instance if none
+        is currently running.
+     */
+    wxAutomationInstance_UseExistingOnly = 0,
+
+    /**
+        Create a new instance if there are no existing ones.
+
+        This flag corresponds to the default behaviour of
+        wxAutomationObject::GetInstance() and means that if getting an existing
+        instance failed, we should call wxAutomationObject::CreateInstance() to
+        create a new one.
+     */
+    wxAutomationInstance_CreateIfNeeded = 1,
+
+    /**
+        Do not show an error message if no existing instance is currently
+        running.
+
+        All other errors will still be reported as usual.
+     */
+    wxAutomationInstance_SilentIfNone = 2
+};
+
+

 /**
     @class wxAutomationObject
 
 /**
     @class wxAutomationObject
 


@@ -103,14 +140,27 @@ public:
         Retrieves the current object associated with the specified ProgID, and
         attaches the IDispatch pointer to this object.
 
         Retrieves the current object associated with the specified ProgID, and
         attaches the IDispatch pointer to this object.
 

+        If attaching to an existing object failed and @a flags includes
+        wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
+        Otherwise this function will normally log an error message which may be
+        undesirable if the object may or may not exist. The
+        wxAutomationInstance_SilentIfNone flag can be used to prevent the error
+        from being logged in this case.
+

         Returns @true if a pointer was successfully retrieved, @false
         otherwise.
         Returns @true if a pointer was successfully retrieved, @false
         otherwise.

+

         Note that this cannot cope with two instances of a given OLE object being
         active simultaneously,
         such as two copies of Excel running. Which object is referenced cannot
         currently be specified.
         Note that this cannot cope with two instances of a given OLE object being
         active simultaneously,
         such as two copies of Excel running. Which object is referenced cannot
         currently be specified.

+
+        @param progId COM ProgID, e.g. "Excel.Application"
+        @param flags The creation flags (this parameters was added in wxWidgets
+            2.9.2)

     */
     */

-    bool GetInstance(const wxString& progId) const;
+    bool GetInstance(const wxString& progId,
+                     int flags = wxAutomationInstance_CreateIfNeeded) const;

 
     /**
         Retrieves a property from this object, assumed to be a dispatch pointer, and
 
     /**
         Retrieves a property from this object, assumed to be a dispatch pointer, and