Added wxAutomationObject documentation, changed some BC++ makefiles

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1135 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/autoobj.tex

@@ -0,0 +1,210 @@
+\section{\class{wxAutomationObject}}\label{wxautomationobject}
+
+The {\bf 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 perform
+automation operations, and set and get properties. The class makes heavy use of the \helpref{wxVariant}{wxvariant} class.
+
+The usage of these classes is quite close to OLE automation usage in Visual 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.
+
+{\small
+\begin{verbatim}
+  wxAutomationObject excelObject;
+  if (excelObject.GetInstance("Excel.Application"))
+      excelObject.PutProperty("ActiveCell.Font.Bold", TRUE);
+\end{verbatim}
+}
+
+Note that this class works under Windows only, and currently only for Visual C++.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{See also}
+
+\helpref{wxVariant}{wxvariant}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxAutomationObject::wxAutomationObject}\label{wxautomationobjectctor}
+
+\func{}{wxAutomationObject}{\param{WXIDISPATCH*}{ dispatchPtr = NULL}}
+
+Constructor, taking an optional IDispatch pointer which will be released when the
+object is deleted.
+
+\membersection{wxAutomationObject::\destruct{wxAutomationObject}}\label{wxautomationobjectdtor}
+
+\func{}{\destruct{wxAutomationObject}}{\void}
+
+Destructor. If the internal IDispatch pointer is non-null, it will be released.
+
+\membersection{wxAutomationObject::CallMethod}\label{wxautomationobjectcallmethod}
+
+\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{int}{ noArgs},
+ \param{wxVariant }{args[]}}
+
+\constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{...}{}}
+
+Calls an automation method for this object. The first form takes a method name, number of
+arguments, and an array of variants. The second form takes a method name and zero to six
+constant references to variants. Since the variant class has constructors for the basic
+data types, and C++ provides temporary objects automatically, both of the following lines
+are syntactically valid:
+
+{\small
+\begin{verbatim}
+  wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
+  wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
+\end{verbatim}
+}
+
+Note that {\it method} can contain dot-separated property names, to save the application
+needing to call GetProperty several times using several temporary objects. For example:
+
+{\small
+\begin{verbatim}
+  object.CallMethod("ActiveCell.Font.ShowDialog", "My caption");
+\end{verbatim}
+}
+
+\membersection{wxAutomationObject::ConvertOleToVariant}\label{wxautomationobjectconvertoletovariant}
+
+\constfunc{bool}{ConvertOleToVariant}{\param{const VARIANTARG\&}{ oleVariant}, \param{const wxVariant\&}{ variant}}
+
+Converts the given VARIANTARG object to a wxVariant. IDispatch pointers are converted to the ``void*" type.
+
+\membersection{wxAutomationObject::ConvertVariantToOle}\label{wxautomationobjectconvertvarianttoole}
+
+\constfunc{bool}{ConvertVariantToOle}{\param{const wxVariant\&}{ variant}, \param{VARIANTARG\&}{ oleVariant}}
+
+Converts the given wxVariant object to a VARIANTARG. The ``void*" type is assumed to be an
+IDispatch pointer.
+
+\membersection{wxAutomationObject::CreateInstance}\label{wxautomationobjectcreateinstance}
+
+\constfunc{bool}{CreateInstance}{\param{const wxString\&}{ classId}}
+
+Creates a new object based on the class id, returning TRUE if the object was successfully created,
+or FALSE if not.
+
+\membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr}
+
+\constfunc{IDispatch*}{GetDispatchPtr}{\void}
+
+Gets the IDispatch pointer.
+
+\membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance}
+
+\constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}}
+
+Retrieves the current object associated with a class id, and attaches the IDispatch pointer
+to this object. Returns TRUE if a pointer was succesfully 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.
+
+\membersection{wxAutomationObject::GetObject}\label{wxautomationobjectgetobject}
+
+\constfunc{bool}{GetObject}{\param{wxAutomationObject\&}{obj} \param{const wxString\&}{ property},
+ \param{int}{ noArgs = 0}, \param{wxVariant }{args[] = NULL}}
+
+Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it.
+To avoid having to deal with IDispatch pointers directly, use this function in preference
+to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects
+from other objects.
+
+Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.
+
+\wxheading{See also}
+
+\helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty}
+
+\membersection{wxAutomationObject::GetProperty}\label{wxautomationobjectgetproperty}
+
+\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
+ \param{wxVariant }{args[]}}
+
+\constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{...}{}}
+
+Gets a property value from this object. The first form takes a property name, number of
+arguments, and an array of variants. The second form takes a property name and zero to six
+constant references to variants. Since the variant class has constructors for the basic
+data types, and C++ provides temporary objects automatically, both of the following lines
+are syntactically valid:
+
+{\small
+\begin{verbatim}
+  wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
+  wxVariant res = obj.GetProperty("Range", "A1");
+\end{verbatim}
+}
+
+Note that {\it property} can contain dot-separated property names, to save the application
+needing to call GetProperty several times using several temporary objects.
+
+\membersection{wxAutomationObject::Invoke}\label{wxautomationobjectinvoke}
+
+\constfunc{bool}{Invoke}{\param{const wxString\&}{ member}, \param{int}{ action},
+ \param{wxVariant\& }{retValue}, \param{int}{ noArgs}, \param{wxVariant}{ args[]},
+ \param{const wxVariant*}{ ptrArgs[] = 0}}
+
+This function is a low-level implementation that allows access to the IDispatch Invoke function.
+It is not meant to be called directly by the application, but is used by other convenience functions.
+
+\wxheading{Parameters}
+
+\docparam{member}{The member function or property name.}
+
+\docparam{action}{Bitlist: may contain DISPATCH\_PROPERTYPUT, DISPATCH\_PROPERTYPUTREF,
+DISPATCH\_METHOD.}
+
+\docparam{retValue}{Return value (ignored if there is no return value)}.
+
+\docparam{noArgs}{Number of arguments in {\it args} or {\it ptrArgs}.}
+
+\docparam{args}{If non-null, contains an array of variants.}
+
+\docparam{ptrArgs}{If non-null, contains an array of constant pointers to variants.}
+
+\wxheading{Return value}
+
+TRUE if the operation was successful, FALSE otherwise.
+
+\wxheading{Remarks}
+
+Two types of argument array are provided, so that when possible pointers are used for efficiency.
+
+\membersection{wxAutomationObject::PutProperty}\label{wxautomationobjectputproperty}
+
+\constfunc{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
+ \param{wxVariant }{args[]}}
+
+\func{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{...}{}}
+
+Puts a property value into this object. The first form takes a property name, number of
+arguments, and an array of variants. The second form takes a property name and zero to six
+constant references to variants. Since the variant class has constructors for the basic
+data types, and C++ provides temporary objects automatically, both of the following lines
+are syntactically valid:
+
+{\small
+\begin{verbatim}
+  obj.PutProperty("Value", wxVariant(23));
+  obj.PutProperty("Value", 23);
+\end{verbatim}
+}
+
+Note that {\it property} can contain dot-separated property names, to save the application
+needing to call GetProperty several times using several temporary objects.
+
+\membersection{wxAutomationObject::SetDispatchPtr}\label{wxautomationobjectsetdispatchptr}
+
+\func{void}{SetDispatchPtr}{\param{WXIDISPATCH*}{ dispatchPtr}}
+
+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.
+

docs/latex/wx/category.tex

@@ -330,6 +330,7 @@ product.
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\helpref{wxAcceleratorTable}{wxacceleratortable}}{Accelerator table}
 \twocolitem{\helpref{wxApp}{wxapp}}{Application class}
+\twocolitem{\helpref{wxAutomationObject}{wxautomationobject}}{OLE automation class}
 \twocolitem{\helpref{wxConfig}{wxconfigbase}}{Classes for configuration reading/writing}
 \twocolitem{\helpref{wxHelpController}{wxhelpcontroller}}{Family of classes for controlling help windows}
 \twocolitem{\helpref{wxLayoutAlgorithm}{wxlayoutalgorithm}}{An alternative window layout facility}

docs/latex/wx/classes.tex

@@ -30,6 +30,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$
 \input accel.tex
 \input activevt.tex
 \input app.tex
+\input autoobj.tex
 \input button.tex
 \input bitmap.tex
 \input bbutton.tex