From 622adc978c4bc91c44399b0366f39bc7d48cf96f Mon Sep 17 00:00:00 2001 From: PB Date: Wed, 23 Aug 2017 19:56:01 +0200 Subject: [PATCH] Improve wxAutomationObject-related documentation --- interface/wx/msw/ole/automtn.h | 131 ++++++++++++++++++--------------- 1 file changed, 73 insertions(+), 58 deletions(-) diff --git a/interface/wx/msw/ole/automtn.h b/interface/wx/msw/ole/automtn.h index fffa47cdb5..7ec55463cf 100644 --- a/interface/wx/msw/ole/automtn.h +++ b/interface/wx/msw/ole/automtn.h @@ -42,7 +42,7 @@ enum wxAutomationInstanceFlags }; /** - Flags used for conversions between wxVariant and OLE VARIANT. + Flags used for conversions between wxVariant and OLE @c VARIANT. These flags are used by wxAutomationObject for its wxConvertOleToVariant() calls. They can be obtained by wxAutomationObject::GetConvertVariantFlags() @@ -60,7 +60,7 @@ enum wxOleConvertVariantFlags wxOleConvertVariant_Default = 0, /** - If this flag is used, SAFEARRAYs contained in OLE VARIANTs will be + If this flag is used, SAFEARRAYs contained in OLE @c VARIANTs will be returned as wxVariants with wxVariantDataSafeArray type instead of wxVariants with the list type containing the (flattened) SAFEARRAY's elements. @@ -72,13 +72,13 @@ enum wxOleConvertVariantFlags /** @class wxVariantDataCurrency - This class represents a thin wrapper for Microsoft Windows CURRENCY type. + This class represents a thin wrapper for Microsoft Windows @c CURRENCY type. - It is used for converting between wxVariant and OLE VARIANT - with type set to VT_CURRENCY. When wxVariant stores + It is used for converting between wxVariant and OLE @c VARIANT + with type set to @c VT_CURRENCY. When wxVariant stores wxVariantDataCurrency, it returns "currency" as its type. - An example of setting and getting CURRENCY value to and from wxVariant: + An example of setting and getting @c CURRENCY value to and from wxVariant: @code CURRENCY cy; wxVariant variant; @@ -137,7 +137,7 @@ public: void SetValue(CURRENCY value); /** - Returns true if @a data is of wxVariantDataCurency type + Returns @true if @a data is of wxVariantDataCurency type and contains the same CURRENCY value. */ virtual bool Eq(wxVariantData& data) const; @@ -171,14 +171,14 @@ public: /** @class wxVariantDataErrorCode - This class represents a thin wrapper for Microsoft Windows SCODE type - (which is the same as HRESULT). + This class represents a thin wrapper for Microsoft Windows @c SCODE type + (which is the same as @c HRESULT). - It is used for converting between a wxVariant and OLE VARIANT with type set - to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns + It is used for converting between a wxVariant and OLE @c VARIANT with type set + to @c VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns "errorcode" as its type. This class can be used for returning error codes of automation calls or exchanging values with other applications: e.g. - Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with + Microsoft Excel returns VARIANTs with @c VT_ERROR type for cell values with errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!" there) etc. See wxVariantDataCurrency for an example of how to exchange values between wxVariant and a native type not directly supported by it. @@ -197,13 +197,13 @@ class wxVariantDataErrorCode : public wxVariantData { public: /** - Constructor initializes the object to @a value or S_OK if no value was + Constructor initializes the object to @a value or @c S_OK if no value was passed. */ wxVariantDataErrorCode(SCODE value = S_OK); /** - Returns the stored SCODE value. + Returns the stored @c SCODE value. */ SCODE GetValue() const; @@ -213,8 +213,8 @@ public: void SetValue(SCODE value); /** - Returns true if @a data is of wxVariantDataErrorCode type - and contains the same SCODE value. + Returns @true if @a data is of wxVariantDataErrorCode type + and contains the same @c SCODE value. */ virtual bool Eq(wxVariantData& data) const; @@ -245,19 +245,19 @@ public: /** @class wxVariantDataSafeArray - This class represents a thin wrapper for Microsoft Windows SAFEARRAY type. + This class represents a thin wrapper for Microsoft Windows @c SAFEARRAY type. - It is used for converting between wxVariant and OLE VARIANT - with type set to VT_ARRAY, which has more than one dimension. + It is used for converting between wxVariant and OLE @c VARIANT + with type set to @c VT_ARRAY, which has more than one dimension. When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type. - wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to. + wxVariantDataSafeArray does NOT manage the @c SAFEARRAY it points to. If you want to pass it to a wxAutomationObject as a parameter: - -# Assign a SAFEARRAY pointer to it and store it in a wxVariant. + -# Assign a @c SAFEARRAY pointer to it and store it in a wxVariant. -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke()) -# wxAutomationObject will destroy the array after the approapriate automation call. - An example of creating a 2-dimensional SAFEARRAY containing VARIANTs + An example of creating a 2-dimensional @c SAFEARRAY containing VARIANTs and storing it in a wxVariant @code SAFEARRAYBOUND bounds[2]; // 2 dimensions @@ -341,7 +341,7 @@ public: void SetValue(SAFEARRAY* value); /** - Returns true if @a data is of wxVariantDataSafeArray type + Returns @true if @a data is of wxVariantDataSafeArray type and contains the same SAFEARRAY* value. */ virtual bool Eq(wxVariantData& data) const; @@ -375,7 +375,7 @@ public: The @b wxAutomationObject class represents an OLE automation object containing a single data member, - an IDispatch pointer. It contains a number of functions that make it easy to + an @c IDispatch pointer. It contains a number of functions that make it easy to perform automation operations, and set and get properties. The class makes heavy use of the wxVariant class. @@ -384,12 +384,13 @@ public: Basic. The API is high-level, and the application can specify multiple properties in a single string. The following example - gets the current Excel instance, and if it exists, makes the active cell bold. + gets the current Microsoft Excel instance, and if it exists, makes the active cell bold. @code wxAutomationObject excelObject; - if (excelObject.GetInstance("Excel.Application")) - excelObject.PutProperty("ActiveCell.Font.Bold", true); + + if ( excelObject.GetInstance("Excel.Application") ) + excelObject.PutProperty("ActiveCell.Font.Bold", true); @endcode Note that this class obviously works under Windows only. @@ -405,14 +406,14 @@ class wxAutomationObject : public wxObject { public: /** - Constructor, taking an optional IDispatch pointer which will be released when + Constructor, taking an optional @c IDispatch pointer which will be released when the object is deleted. */ wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL); /** - Destructor. If the internal IDispatch pointer is non-null, it will be released. + Destructor. If the internal @c IDispatch pointer is non-null, it will be released. */ ~wxAutomationObject(); @@ -427,11 +428,18 @@ public: data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid: + @code + wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4)); + wxVariant res = obj.CallMethod("Sum", 1.2, 3.4); + @endcode Note that @a method can contain dot-separated property names, to save the application - needing to call GetProperty several times using several temporary objects. For + needing to call GetProperty() several times using several temporary objects. For example: + @code + object.CallMethod("ActiveWorkbook.ActiveSheet.Protect", "MyPassword"); + @endcode */ wxVariant CallMethod(const wxString& method, int noArgs, wxVariant args[]) const; @@ -439,7 +447,7 @@ public: //@} /** - Creates a new object based on the ProgID, returning @true if the object was + Creates a new object based on the @a progID, returning @true if the object was successfully created, or @false if not. */ @@ -449,14 +457,14 @@ public: Checks if the object is in a valid state. Returns @true if the object was successfully initialized or @false if - it has no valid IDispatch pointer. + it has no valid @c IDispatch pointer. - @see GetDispatchPtr() + @see GetDispatchPtr(), GetInstance() */ bool IsOk() const; /** - Gets the IDispatch pointer. + Gets the @c IDispatch pointer. Notice that the return value of this function is an untyped pointer but it can be safely cast to @c IDispatch. @@ -465,13 +473,13 @@ public: /** Retrieves the current object associated with the specified ProgID, and - attaches the IDispatch pointer to this object. + attaches the @c 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. + ::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 + ::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 @@ -479,7 +487,7 @@ public: 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 + such as two copies of Microsoft Excel running. Which object is referenced cannot currently be specified. @param progId COM ProgID, e.g. "Excel.Application" @@ -492,11 +500,11 @@ public: /** Retrieves a property from this object, assumed to be a dispatch pointer, and initialises @a obj with it. - To avoid having to deal with IDispatch pointers directly, use this function in + To avoid having to deal with @c IDispatch pointers directly, use this function in preference to GetProperty() when retrieving objects from other objects. - Note that an IDispatch pointer is stored as a void* pointer in wxVariant + Note that an @c IDispatch pointer is stored as a @c void* pointer in wxVariant objects. @see GetProperty() @@ -516,7 +524,11 @@ public: data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid: - + @code + wxVariant res = obj.GetProperty("Range", wxVariant("A1")); + wxVariant res = obj.GetProperty("Range", "A1"); + @endcode + Note that @a property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects. @@ -527,7 +539,7 @@ public: //@} /** - This function is a low-level implementation that allows access to the IDispatch + This function is a low-level implementation that allows access to the @c IDispatch Invoke function. It is not meant to be called directly by the application, but is used by other convenience functions. @@ -535,8 +547,8 @@ public: @param member The member function or property name. @param action - Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF, - DISPATCH_METHOD. + Bitlist: may contain @c DISPATCH_PROPERTYPUT, @c DISPATCH_PROPERTYPUTREF, + @c DISPATCH_PROPERTYGET, @c DISPATCH_METHOD. @param retValue Return value (ignored if there is no return value) @param noArgs @@ -567,10 +579,14 @@ public: data types, and C++ provides temporary objects automatically, both of the following lines are syntactically valid: + @code + obj.PutProperty("Value", wxVariant(23)); + obj.PutProperty("Value", 23); + @endcode Note that @a property can contain dot-separated property names, to save the application - needing to call GetProperty several times using several temporary objects. + needing to call GetProperty() several times using several temporary objects. */ bool PutProperty(const wxString& property, int noArgs, wxVariant args[]); @@ -578,41 +594,40 @@ public: //@} /** - Sets the IDispatch pointer. This function does not check if there is already an - IDispatch pointer. - You may need to cast from IDispatch* to WXIDISPATCH* when calling this function. + Sets the @c IDispatch pointer, does not check if there is already one. + You may need to cast from @c IDispatch* to @c WXIDISPATCH* when calling this function. */ void SetDispatchPtr(WXIDISPATCH* dispatchPtr); /** Returns the locale identifier used in automation calls. - The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by + The default is @c LOCALE_SYSTEM_DEFAULT but the objects obtained by GetObject() inherit the locale identifier from the one that created them. @since 2.9.5 */ - LCID GetLCID() const; + WXLCID GetLCID() const; /** Sets the locale identifier to be used in automation calls performed by this object. - The default value is LOCALE_SYSTEM_DEFAULT. + The default value is @c LOCALE_SYSTEM_DEFAULT. Notice that any automation objects created by this one inherit the same - LCID. + @c LCID. @since 2.9.5 */ - void SetLCID(LCID lcid); + void SetLCID(WXLCID lcid); /** Returns the flags used for conversions between wxVariant and OLE - VARIANT, see wxOleConvertVariantFlags. + @c VARIANT, see #wxOleConvertVariantFlags. - The default value is wxOleConvertVariant_Default for compatibility but + The default value is ::wxOleConvertVariant_Default for compatibility but it can be changed using SetConvertVariantFlags(). Notice that objects obtained by GetObject() inherit the flags from the @@ -623,10 +638,10 @@ public: long GetConvertVariantFlags() const; /** - Sets the flags used for conversions between wxVariant and OLE VARIANT, - see wxOleConvertVariantFlags. + Sets the flags used for conversions between wxVariant and OLE @c VARIANT, + see #wxOleConvertVariantFlags. - The default value is wxOleConvertVariant_Default. + The default value is ::wxOleConvertVariant_Default. @since 3.0 */