docs/latex/wx/autoobj.tex

   1 \section{\class{wxAutomationObject}}\label{wxautomationobject}
   2
   3 The {\bf wxAutomationObject} class represents an OLE automation object containing a single data member,
   4 an IDispatch pointer. It contains a number of functions that make it easy to perform
   5 automation operations, and set and get properties. The class makes heavy use of the \helpref{wxVariant}{wxvariant} class.
   6
   7 The usage of these classes is quite close to OLE automation usage in Visual Basic. The API is
   8 high-level, and the application can specify multiple properties in a single string. The following example
   9 gets the current Excel instance, and if it exists, makes the active cell bold.
  10
  11 {\small
  12 \begin{verbatim}
  13   wxAutomationObject excelObject;
  14   if (excelObject.GetInstance("Excel.Application"))
  15       excelObject.PutProperty("ActiveCell.Font.Bold", true);
  16 \end{verbatim}
  17 }
  18
  19 Note that this class obviously works under Windows only.
  20
  21 \wxheading{Derived from}
  22
  23 \helpref{wxObject}{wxobject}
  24
  25 \wxheading{Include files}
  26
  27 <wx/msw/ole/automtn.h>
  28
  29 \wxheading{Library}
  30
  31 \helpref{wxCore}{librarieslist}
  32
  33 \wxheading{See also}
  34
  35 \helpref{wxVariant}{wxvariant}
  36
  37 \latexignore{\rtfignore{\wxheading{Members}}}
  38
  39 \membersection{wxAutomationObject::wxAutomationObject}\label{wxautomationobjectctor}
  40
  41 \func{}{wxAutomationObject}{\param{WXIDISPATCH*}{ dispatchPtr = NULL}}
  42
  43 Constructor, taking an optional IDispatch pointer which will be released when the
  44 object is deleted.
  45
  46 \membersection{wxAutomationObject::\destruct{wxAutomationObject}}\label{wxautomationobjectdtor}
  47
  48 \func{}{\destruct{wxAutomationObject}}{\void}
  49
  50 Destructor. If the internal IDispatch pointer is non-null, it will be released.
  51
  52 \membersection{wxAutomationObject::CallMethod}\label{wxautomationobjectcallmethod}
  53
  54 \constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{int}{ noArgs},
  55  \param{wxVariant }{args[]}}
  56
  57 \constfunc{wxVariant}{CallMethod}{\param{const wxString\&}{ method}, \param{...}{}}
  58
  59 Calls an automation method for this object. The first form takes a method name, number of
  60 arguments, and an array of variants. The second form takes a method name and zero to six
  61 constant references to variants. Since the variant class has constructors for the basic
  62 data types, and C++ provides temporary objects automatically, both of the following lines
  63 are syntactically valid:
  64
  65 {\small
  66 \begin{verbatim}
  67   wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
  68   wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
  69 \end{verbatim}
  70 }
  71
  72 Note that {\it method} can contain dot-separated property names, to save the application
  73 needing to call GetProperty several times using several temporary objects. For example:
  74
  75 {\small
  76 \begin{verbatim}
  77   object.CallMethod("ActiveCell.Font.ShowDialog", "My caption");
  78 \end{verbatim}
  79 }
  80
  81 \membersection{wxAutomationObject::CreateInstance}\label{wxautomationobjectcreateinstance}
  82
  83 \constfunc{bool}{CreateInstance}{\param{const wxString\&}{ classId}}
  84
  85 Creates a new object based on the class id, returning true if the object was successfully created,
  86 or false if not.
  87
  88 \membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr}
  89
  90 \constfunc{IDispatch*}{GetDispatchPtr}{\void}
  91
  92 Gets the IDispatch pointer.
  93
  94 \membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance}
  95
  96 \constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}}
  97
  98 Retrieves the current object associated with a class id, and attaches the IDispatch pointer
  99 to this object. Returns true if a pointer was successfully retrieved, false otherwise.
 100
 101 Note that this cannot cope with two instances of a given OLE object being active simultaneously,
 102 such as two copies of Excel running. Which object is referenced cannot currently be specified.
 103
 104 \membersection{wxAutomationObject::GetObject}\label{wxautomationobjectgetobject}
 105
 106 \constfunc{bool}{GetObject}{\param{wxAutomationObject\&}{obj}, \param{const wxString\&}{ property},
 107  \param{int}{ noArgs = 0}, \param{wxVariant }{args[] = NULL}}
 108
 109 Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it.
 110 To avoid having to deal with IDispatch pointers directly, use this function in preference
 111 to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects
 112 from other objects.
 113
 114 Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.
 115
 116 \wxheading{See also}
 117
 118 \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty}
 119
 120 \membersection{wxAutomationObject::GetProperty}\label{wxautomationobjectgetproperty}
 121
 122 \constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
 123  \param{wxVariant }{args[]}}
 124
 125 \constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{...}{}}
 126
 127 Gets a property value from this object. The first form takes a property name, number of
 128 arguments, and an array of variants. The second form takes a property name and zero to six
 129 constant references to variants. Since the variant class has constructors for the basic
 130 data types, and C++ provides temporary objects automatically, both of the following lines
 131 are syntactically valid:
 132
 133 {\small
 134 \begin{verbatim}
 135   wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
 136   wxVariant res = obj.GetProperty("Range", "A1");
 137 \end{verbatim}
 138 }
 139
 140 Note that {\it property} can contain dot-separated property names, to save the application
 141 needing to call GetProperty several times using several temporary objects.
 142
 143 \membersection{wxAutomationObject::Invoke}\label{wxautomationobjectinvoke}
 144
 145 \constfunc{bool}{Invoke}{\param{const wxString\&}{ member}, \param{int}{ action},
 146  \param{wxVariant\& }{retValue}, \param{int}{ noArgs}, \param{wxVariant}{ args[]},
 147  \param{const wxVariant*}{ ptrArgs[] = 0}}
 148
 149 This function is a low-level implementation that allows access to the IDispatch Invoke function.
 150 It is not meant to be called directly by the application, but is used by other convenience functions.
 151
 152 \wxheading{Parameters}
 153
 154 \docparam{member}{The member function or property name.}
 155
 156 \docparam{action}{Bitlist: may contain DISPATCH\_PROPERTYPUT, DISPATCH\_PROPERTYPUTREF,
 157 DISPATCH\_METHOD.}
 158
 159 \docparam{retValue}{Return value (ignored if there is no return value)}.
 160
 161 \docparam{noArgs}{Number of arguments in {\it args} or {\it ptrArgs}.}
 162
 163 \docparam{args}{If non-null, contains an array of variants.}
 164
 165 \docparam{ptrArgs}{If non-null, contains an array of constant pointers to variants.}
 166
 167 \wxheading{Return value}
 168
 169 true if the operation was successful, false otherwise.
 170
 171 \wxheading{Remarks}
 172
 173 Two types of argument array are provided, so that when possible pointers are used for efficiency.
 174
 175 \membersection{wxAutomationObject::PutProperty}\label{wxautomationobjectputproperty}
 176
 177 \constfunc{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
 178  \param{wxVariant }{args[]}}
 179
 180 \func{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{...}{}}
 181
 182 Puts a property value into this object. The first form takes a property name, number of
 183 arguments, and an array of variants. The second form takes a property name and zero to six
 184 constant references to variants. Since the variant class has constructors for the basic
 185 data types, and C++ provides temporary objects automatically, both of the following lines
 186 are syntactically valid:
 187
 188 {\small
 189 \begin{verbatim}
 190   obj.PutProperty("Value", wxVariant(23));
 191   obj.PutProperty("Value", 23);
 192 \end{verbatim}
 193 }
 194
 195 Note that {\it property} can contain dot-separated property names, to save the application
 196 needing to call GetProperty several times using several temporary objects.
 197
 198 \membersection{wxAutomationObject::SetDispatchPtr}\label{wxautomationobjectsetdispatchptr}
 199
 200 \func{void}{SetDispatchPtr}{\param{WXIDISPATCH*}{ dispatchPtr}}
 201
 202 Sets the IDispatch pointer. This function does not check if there is already an IDispatch pointer.
 203
 204 You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 205