1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the ActiveQt framework of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:BSD$
9 ** You may use this file under the terms of the BSD license as follows:
10 **
11 ** "Redistribution and use in source and binary forms, with or without
12 ** modification, are permitted provided that the following conditions are
13 ** met:
14 ** * Redistributions of source code must retain the above copyright
15 ** notice, this list of conditions and the following disclaimer.
16 ** * Redistributions in binary form must reproduce the above copyright
17 ** notice, this list of conditions and the following disclaimer in
18 ** the documentation and/or other materials provided with the
19 ** distribution.
20 ** * Neither the name of The Qt Company Ltd nor the names of its
21 ** contributors may be used to endorse or promote products derived
22 ** from this software without specific prior written permission.
23 **
24 **
25 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
36 **
37 ** $QT_END_LICENSE$
38 **
39 ****************************************************************************/
40
41 #include "qaxbase.h"
42
43 #ifndef QT_NO_WIN_ACTIVEQT
44
45 #include <qmetaobject.h>
46 #include <quuid.h>
47 #include <qt_windows.h>
48 #include <qtextstream.h>
49
50 #include <ctype.h>
51
52 #include "../shared/qaxtypes.h"
53
54 QT_BEGIN_NAMESPACE
55
qax_docuFromName(ITypeInfo * typeInfo,const QString & name)56 QString qax_docuFromName(ITypeInfo *typeInfo, const QString &name)
57 {
58 QString docu;
59 if (!typeInfo)
60 return docu;
61
62 MEMBERID memId;
63 BSTR names = QStringToBSTR(name);
64 typeInfo->GetIDsOfNames((BSTR*)&names, 1, &memId);
65 SysFreeString(names);
66 if (memId != DISPID_UNKNOWN) {
67 BSTR docStringBstr, helpFileBstr;
68 ulong helpContext;
69 HRESULT hres = typeInfo->GetDocumentation(memId, 0, &docStringBstr, &helpContext, &helpFileBstr);
70 QString docString = QString::fromWCharArray(docStringBstr);
71 QString helpFile = QString::fromWCharArray(helpFileBstr);
72 SysFreeString(docStringBstr);
73 SysFreeString(helpFileBstr);
74 if (hres == S_OK) {
75 if (!docString.isEmpty())
76 docu += docString + QLatin1String("\n");
77 if (!helpFile.isEmpty())
78 docu += QString::fromLatin1("For more information, see help context %1 in %2.").arg((uint)helpContext).arg(helpFile);
79 }
80 }
81
82 return docu;
83 }
84
docuFromName(ITypeInfo * typeInfo,const QString & name)85 static inline QString docuFromName(ITypeInfo *typeInfo, const QString &name)
86 {
87 return QLatin1String("<p>") + qax_docuFromName(typeInfo, name) + QLatin1String("\n");
88 }
89
namedPrototype(const QList<QByteArray> & parameterTypes,const QList<QByteArray> & parameterNames,int numDefArgs=0)90 static QByteArray namedPrototype(const QList<QByteArray> ¶meterTypes, const QList<QByteArray> ¶meterNames, int numDefArgs = 0)
91 {
92 QByteArray prototype("(");
93 for (int p = 0; p < parameterTypes.count(); ++p) {
94 QByteArray type(parameterTypes.at(p));
95 prototype += type;
96
97 if (p < parameterNames.count())
98 prototype += ' ' + parameterNames.at(p);
99
100 if (numDefArgs >= parameterTypes.count() - p)
101 prototype += " = 0";
102 if (p < parameterTypes.count() - 1)
103 prototype += ", ";
104 }
105 prototype += ')';
106
107 return prototype;
108 }
109
toType(const QByteArray & t)110 static QByteArray toType(const QByteArray &t)
111 {
112 QByteArray type = t;
113 int vartype = QVariant::nameToType(type);
114 if (vartype == QVariant::Invalid)
115 type = "int";
116
117 if (type.at(0) == 'Q')
118 type = type.mid(1);
119 type[0] = toupper(type.at(0));
120 if (type == "VariantList")
121 type = "List";
122 else if (type == "Map<QVariant,QVariant>")
123 type = "Map";
124 else if (type == "Uint")
125 type = "UInt";
126
127 return "to" + type + "()";
128 }
129
qax_generateDocumentation(QAxBase * that)130 QString qax_generateDocumentation(QAxBase *that)
131 {
132 that->metaObject();
133
134 if (that->isNull())
135 return QString();
136
137 ITypeInfo *typeInfo = 0;
138 IDispatch *dispatch = 0;
139 that->queryInterface(IID_IDispatch, (void**)&dispatch);
140 if (dispatch)
141 dispatch->GetTypeInfo(0, LOCALE_SYSTEM_DEFAULT, &typeInfo);
142
143 QString docu;
144 QTextStream stream(&docu, QIODevice::WriteOnly);
145
146 const QMetaObject *mo = that->metaObject();
147 QString coClass = QLatin1String(mo->classInfo(mo->indexOfClassInfo("CoClass")).value());
148
149 stream << "<h1 align=center>" << coClass << " Reference</h1>" << endl;
150 stream << "<p>The " << coClass << " COM object is a " << that->qObject()->metaObject()->className();
151 stream << " with the CLSID " << that->control() << ".</p>" << endl;
152
153 stream << "<h3>Interfaces</h3>" << endl;
154 stream << "<ul>" << endl;
155 const char *inter = 0;
156 int interCount = 1;
157 while ((inter = mo->classInfo(mo->indexOfClassInfo("Interface " + QByteArray::number(interCount))).value())) {
158 stream << "<li>" << inter << endl;
159 interCount++;
160 }
161 stream << "</ul>" << endl;
162
163 stream << "<h3>Event Interfaces</h3>" << endl;
164 stream << "<ul>" << endl;
165 interCount = 1;
166 while ((inter = mo->classInfo(mo->indexOfClassInfo("Event Interface " + QByteArray::number(interCount))).value())) {
167 stream << "<li>" << inter << endl;
168 interCount++;
169 }
170 stream << "</ul>" << endl;
171
172 QList<QString> methodDetails, propDetails;
173
174 const int slotCount = mo->methodCount();
175 if (slotCount) {
176 stream << "<h2>Public Slots:</h2>" << endl;
177 stream << "<ul>" << endl;
178
179 int defArgCount = 0;
180 for (int islot = mo->methodOffset(); islot < slotCount; ++islot) {
181 const QMetaMethod slot = mo->method(islot);
182 if (slot.methodType() != QMetaMethod::Slot)
183 continue;
184
185 if (slot.attributes() & QMetaMethod::Cloned) {
186 ++defArgCount;
187 continue;
188 }
189
190 QByteArray returntype(slot.typeName());
191 if (returntype.isEmpty())
192 returntype = "void";
193 QByteArray prototype = namedPrototype(slot.parameterTypes(), slot.parameterNames(), defArgCount);
194 QByteArray signature = slot.signature();
195 QByteArray name = signature.left(signature.indexOf('('));
196 stream << "<li>" << returntype << " <a href=\"#" << name << "\"><b>" << name << "</b></a>" << prototype << ";</li>" << endl;
197
198 prototype = namedPrototype(slot.parameterTypes(), slot.parameterNames());
199 QString detail = QString::fromLatin1("<h3><a name=") + QString::fromLatin1(name.constData()) + QLatin1String("></a>") +
200 QLatin1String(returntype.constData()) + QLatin1Char(' ') +
201 QLatin1String(name.constData()) + QLatin1Char(' ') +
202 QString::fromLatin1(prototype.constData()) + QLatin1String("<tt> [slot]</tt></h3>\n");
203 prototype = namedPrototype(slot.parameterTypes(), QList<QByteArray>());
204 detail += docuFromName(typeInfo, QString::fromLatin1(name.constData()));
205 detail += QLatin1String("<p>Connect a signal to this slot:<pre>\n");
206 detail += QString::fromLatin1("\tQObject::connect(sender, SIGNAL(someSignal") + QString::fromLatin1(prototype.constData()) +
207 QLatin1String("), object, SLOT(") + QString::fromLatin1(name.constData()) +
208 QString::fromLatin1(prototype.constData()) + QLatin1String("));");
209 detail += QLatin1String("</pre>\n");
210
211 if (1) {
212 detail += QLatin1String("<p>Or call the function directly:<pre>\n");
213
214 bool hasParams = slot.parameterTypes().count() != 0;
215 if (hasParams)
216 detail += QLatin1String("\tQVariantList params = ...\n");
217 detail += QLatin1String("\t");
218 QByteArray functionToCall = "dynamicCall";
219 if (returntype == "IDispatch*" || returntype == "IUnknown*") {
220 functionToCall = "querySubObject";
221 returntype = "QAxObject *";
222 }
223 if (returntype != "void")
224 detail += QLatin1String(returntype.constData()) + QLatin1String(" result = ");
225 detail += QLatin1String("object->") + QLatin1String(functionToCall.constData()) +
226 QLatin1String("(\"" + name + prototype + '\"');
227 if (hasParams)
228 detail += QLatin1String(", params");
229 detail += QLatin1Char(')');
230 if (returntype != "void" && returntype != "QAxObject *" && returntype != "QVariant")
231 detail += QLatin1Char('.') + QLatin1String(toType(returntype));
232 detail += QLatin1String(";</pre>\n");
233 } else {
234 detail += QLatin1String("<p>This function has parameters of unsupported types and cannot be called directly.");
235 }
236
237 methodDetails << detail;
238 defArgCount = 0;
239 }
240
241 stream << "</ul>" << endl;
242 }
243 int signalCount = mo->methodCount();
244 if (signalCount) {
245 ITypeLib *typeLib = 0;
246 if (typeInfo) {
247 UINT index = 0;
248 typeInfo->GetContainingTypeLib(&typeLib, &index);
249 typeInfo->Release();
250 }
251 typeInfo = 0;
252
253 stream << "<h2>Signals:</h2>" << endl;
254 stream << "<ul>" << endl;
255
256 for (int isignal = mo->methodOffset(); isignal < signalCount; ++isignal) {
257 const QMetaMethod signal(mo->method(isignal));
258 if (signal.methodType() != QMetaMethod::Signal)
259 continue;
260
261 QByteArray prototype = namedPrototype(signal.parameterTypes(), signal.parameterNames());
262 QByteArray signature = signal.signature();
263 QByteArray name = signature.left(signature.indexOf('('));
264 stream << "<li>void <a href=\"#" << name << "\"><b>" << name << "</b></a>" << prototype << ";</li>" << endl;
265
266 QString detail = QLatin1String("<h3><a name=") + QLatin1String(name.constData()) + QLatin1String("></a>void ") +
267 QLatin1String(name.constData()) + QLatin1Char(' ') +
268 QLatin1String(prototype.constData()) + QLatin1String("<tt> [signal]</tt></h3>\n");
269 if (typeLib) {
270 interCount = 0;
271 do {
272 if (typeInfo)
273 typeInfo->Release();
274 typeInfo = 0;
275 typeLib->GetTypeInfo(++interCount, &typeInfo);
276 QString typeLibDocu = docuFromName(typeInfo, QString::fromLatin1(name.constData()));
277 if (!typeLibDocu.isEmpty()) {
278 detail += typeLibDocu;
279 break;
280 }
281 } while (typeInfo);
282 }
283 prototype = namedPrototype(signal.parameterTypes(), QList<QByteArray>());
284 detail += QLatin1String("<p>Connect a slot to this signal:<pre>\n");
285 detail += QLatin1String("\tQObject::connect(object, SIGNAL(") + QString::fromLatin1(name.constData()) +
286 QString::fromLatin1(prototype.constData()) +
287 QLatin1String("), receiver, SLOT(someSlot") + QString::fromLatin1(prototype.constData()) + QLatin1String("));");
288 detail += QLatin1String("</pre>\n");
289
290 methodDetails << detail;
291 if (typeInfo)
292 typeInfo->Release();
293 typeInfo = 0;
294 }
295 stream << "</ul>" << endl;
296
297 if (typeLib)
298 typeLib->Release();
299 }
300
301 const int propCount = mo->propertyCount();
302 if (propCount) {
303 if (dispatch)
304 dispatch->GetTypeInfo(0, LOCALE_SYSTEM_DEFAULT, &typeInfo);
305 stream << "<h2>Properties:</h2>" << endl;
306 stream << "<ul>" << endl;
307
308 for (int iprop = 0; iprop < propCount; ++iprop) {
309 const QMetaProperty prop = mo->property(iprop);
310 QByteArray name(prop.name());
311 QByteArray type(prop.typeName());
312
313 stream << "<li>" << type << " <a href=\"#" << name << "\"><b>" << name << "</b></a>;</li>" << endl;
314 QString detail = QLatin1String("<h3><a name=") + QString::fromLatin1(name.constData()) + QLatin1String("></a>") +
315 QLatin1String(type.constData()) +
316 QLatin1Char(' ') + QLatin1String(name.constData()) + QLatin1String("</h3>\n");
317 detail += docuFromName(typeInfo, QString::fromLatin1(name));
318 QVariant::Type vartype = QVariant::nameToType(type);
319 if (!prop.isReadable())
320 continue;
321
322 if (prop.isEnumType())
323 vartype = QVariant::Int;
324
325 if (vartype != QVariant::Invalid) {
326 detail += QLatin1String("<p>Read this property's value using QObject::property:<pre>\n");
327 if (prop.isEnumType())
328 detail += QLatin1String("\tint val = ");
329 else
330 detail += QLatin1Char('\t') + QLatin1String(type.constData()) + QLatin1String(" val = ");
331 detail += QLatin1String("object->property(\"") + QLatin1String(name.constData()) +
332 QLatin1String("\").") + QLatin1String(toType(type).constData()) + QLatin1String(";\n");
333 detail += QLatin1String("</pre>\n");
334 } else if (type == "IDispatch*" || type == "IUnknown*") {
335 detail += QLatin1String("<p>Get the subobject using querySubObject:<pre>\n");
336 detail += QLatin1String("\tQAxObject *") + QLatin1String(name.constData()) +
337 QLatin1String(" = object->querySubObject(\"") + QLatin1String(name.constData()) + QLatin1String("\");\n");
338 detail += QLatin1String("</pre>\n");
339 } else {
340 detail += QLatin1String("<p>This property is of an unsupported type.\n");
341 }
342 if (prop.isWritable()) {
343 detail += QLatin1String("Set this property' value using QObject::setProperty:<pre>\n");
344 if (prop.isEnumType()) {
345 detail += QLatin1String("\tint newValue = ... // string representation of values also supported\n");
346 } else {
347 detail += QLatin1String("\t") + QString::fromLatin1(type.constData()) + QLatin1String(" newValue = ...\n");
348 }
349 detail += QLatin1String("\tobject->setProperty(\"") + QString::fromLatin1(name) + QLatin1String("\", newValue);\n");
350 detail += QLatin1String("</pre>\n");
351 detail += QLatin1String("Or using the ");
352 QByteArray setterSlot;
353 if (isupper(name.at(0))) {
354 setterSlot = "Set" + name;
355 } else {
356 QByteArray nameUp = name;
357 nameUp[0] = toupper(nameUp.at(0));
358 setterSlot = "set" + nameUp;
359 }
360 detail += QLatin1String("<a href=\"#") + QString::fromLatin1(setterSlot) + QLatin1String("\">") +
361 QString::fromLatin1(setterSlot.constData()) + QLatin1String("</a> slot.\n");
362 }
363 if (prop.isEnumType()) {
364 detail += QLatin1String("<p>See also <a href=\"#") + QString::fromLatin1(type) +
365 QLatin1String("\">") + QString::fromLatin1(type) + QLatin1String("</a>.\n");
366 }
367
368 propDetails << detail;
369 }
370 stream << "</ul>" << endl;
371 }
372
373 const int enumCount = mo->enumeratorCount();
374 if (enumCount) {
375 stream << "<hr><h2>Member Type Documentation</h2>" << endl;
376 for (int i = 0; i < enumCount; ++i) {
377 const QMetaEnum enumdata = mo->enumerator(i);
378 stream << "<h3><a name=" << enumdata.name() << "></a>" << enumdata.name() << "</h3>" << endl;
379 stream << "<ul>" << endl;
380 for (int e = 0; e < enumdata.keyCount(); ++e) {
381 stream << "<li>" << enumdata.key(e) << "\t=" << enumdata.value(e) << "</li>" << endl;
382 }
383 stream << "</ul>" << endl;
384 }
385 }
386 if (methodDetails.count()) {
387 stream << "<hr><h2>Member Function Documentation</h2>" << endl;
388 for (int i = 0; i < methodDetails.count(); ++i)
389 stream << methodDetails.at(i) << endl;
390 }
391 if (propDetails.count()) {
392 stream << "<hr><h2>Property Documentation</h2>" << endl;
393 for (int i = 0; i < propDetails.count(); ++i)
394 stream << propDetails.at(i) << endl;
395 }
396
397 if (typeInfo)
398 typeInfo->Release();
399 if (dispatch)
400 dispatch->Release();
401 return docu;
402 }
403
404 QT_END_NAMESPACE
405 #endif // QT_NO_WIN_ACTIVEQT
406