Improve wxAutomationObject-related documentation
This commit is contained in:
PB
@@ -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,10 +384,11 @@ 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);
|
||||
@endcode
|
||||
@@ -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,6 +524,10 @@ 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
|
||||
@@ -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
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user