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{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::CreateInstance}\label{wxautomationobjectcreateinstance}
  78
  79 \constfunc{bool}{CreateInstance}{\param{const wxString\&}{ classId}}
  80
  81 Creates a new object based on the class id, returning true if the object was successfully created,
  82 or false if not.
  83
  84 \membersection{wxAutomationObject::GetDispatchPtr}\label{wxautomationobjectgetdispatchptr}
  85
  86 \constfunc{IDispatch*}{GetDispatchPtr}{\void}
  87
  88 Gets the IDispatch pointer.
  89
  90 \membersection{wxAutomationObject::GetInstance}\label{wxautomationobjectgetinstance}
  91
  92 \constfunc{bool}{GetInstance}{\param{const wxString\&}{ classId}}
  93
  94 Retrieves the current object associated with a class id, and attaches the IDispatch pointer
  95 to this object. Returns true if a pointer was successfully retrieved, false otherwise.
  96
  97 Note that this cannot cope with two instances of a given OLE object being active simultaneously,
  98 such as two copies of Excel running. Which object is referenced cannot currently be specified.
  99
 100 \membersection{wxAutomationObject::GetObject}\label{wxautomationobjectgetobject}
 101
 102 \constfunc{bool}{GetObject}{\param{wxAutomationObject\&}{obj} \param{const wxString\&}{ property},
 103  \param{int}{ noArgs = 0}, \param{wxVariant }{args[] = NULL}}
 104
 105 Retrieves a property from this object, assumed to be a dispatch pointer, and initialises {\it obj} with it.
 106 To avoid having to deal with IDispatch pointers directly, use this function in preference
 107 to \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty} when retrieving objects
 108 from other objects.
 109
 110 Note that an IDispatch pointer is stored as a void* pointer in wxVariant objects.
 111
 112 \wxheading{See also}
 113
 114 \helpref{wxAutomationObject::GetProperty}{wxautomationobjectgetproperty}
 115
 116 \membersection{wxAutomationObject::GetProperty}\label{wxautomationobjectgetproperty}
 117
 118 \constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
 119  \param{wxVariant }{args[]}}
 120
 121 \constfunc{wxVariant}{GetProperty}{\param{const wxString\&}{ property}, \param{...}{}}
 122
 123 Gets a property value from this object. The first form takes a property name, number of
 124 arguments, and an array of variants. The second form takes a property name and zero to six
 125 constant references to variants. Since the variant class has constructors for the basic
 126 data types, and C++ provides temporary objects automatically, both of the following lines
 127 are syntactically valid:
 128
 129 {\small
 130 \begin{verbatim}
 131   wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
 132   wxVariant res = obj.GetProperty("Range", "A1");
 133 \end{verbatim}
 134 }
 135
 136 Note that {\it property} can contain dot-separated property names, to save the application
 137 needing to call GetProperty several times using several temporary objects.
 138
 139 \membersection{wxAutomationObject::Invoke}\label{wxautomationobjectinvoke}
 140
 141 \constfunc{bool}{Invoke}{\param{const wxString\&}{ member}, \param{int}{ action},
 142  \param{wxVariant\& }{retValue}, \param{int}{ noArgs}, \param{wxVariant}{ args[]},
 143  \param{const wxVariant*}{ ptrArgs[] = 0}}
 144
 145 This function is a low-level implementation that allows access to the IDispatch Invoke function.
 146 It is not meant to be called directly by the application, but is used by other convenience functions.
 147
 148 \wxheading{Parameters}
 149
 150 \docparam{member}{The member function or property name.}
 151
 152 \docparam{action}{Bitlist: may contain DISPATCH\_PROPERTYPUT, DISPATCH\_PROPERTYPUTREF,
 153 DISPATCH\_METHOD.}
 154
 155 \docparam{retValue}{Return value (ignored if there is no return value)}.
 156
 157 \docparam{noArgs}{Number of arguments in {\it args} or {\it ptrArgs}.}
 158
 159 \docparam{args}{If non-null, contains an array of variants.}
 160
 161 \docparam{ptrArgs}{If non-null, contains an array of constant pointers to variants.}
 162
 163 \wxheading{Return value}
 164
 165 true if the operation was successful, false otherwise.
 166
 167 \wxheading{Remarks}
 168
 169 Two types of argument array are provided, so that when possible pointers are used for efficiency.
 170
 171 \membersection{wxAutomationObject::PutProperty}\label{wxautomationobjectputproperty}
 172
 173 \constfunc{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{int}{ noArgs},
 174  \param{wxVariant }{args[]}}
 175
 176 \func{bool}{PutProperty}{\param{const wxString\&}{ property}, \param{...}{}}
 177
 178 Puts a property value into this object. The first form takes a property name, number of
 179 arguments, and an array of variants. The second form takes a property name and zero to six
 180 constant references to variants. Since the variant class has constructors for the basic
 181 data types, and C++ provides temporary objects automatically, both of the following lines
 182 are syntactically valid:
 183
 184 {\small
 185 \begin{verbatim}
 186   obj.PutProperty("Value", wxVariant(23));
 187   obj.PutProperty("Value", 23);
 188 \end{verbatim}
 189 }
 190
 191 Note that {\it property} can contain dot-separated property names, to save the application
 192 needing to call GetProperty several times using several temporary objects.
 193
 194 \membersection{wxAutomationObject::SetDispatchPtr}\label{wxautomationobjectsetdispatchptr}
 195
 196 \func{void}{SetDispatchPtr}{\param{WXIDISPATCH*}{ dispatchPtr}}
 197
 198 Sets the IDispatch pointer. This function does not check if there is already an IDispatch pointer.
 199
 200 You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
 201