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