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