Update copyright headers
[qt:qt.git] / doc / src / development / activeqt-dumpcpp.qdoc
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 documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*! 
29     \page activeqt-dumpcpp.html
30     \title The dumpcpp Tool (ActiveQt)
31
32     \ingroup activeqt-tools
33
34     \keyword dumpcpp
35
36     The \c dumpcpp tool generates a C++ namespace for a type library.
37
38     To generate a C++ namespace for a type library, call \c dumpcpp with the following 
39     command line parameters:
40
41     \table
42     \header
43     \i Option
44     \i Result
45     \row
46     \i input
47     \i Generate documentation for \e input. \e input can specify a type library file or a type 
48     library ID, or a CLSID or ProgID for an object
49     \row
50     \i -o file
51     \i Writes the class declaration to \e {file}.h and meta object infomation to \e {file}.cpp
52     \row
53     \i -n namespace
54     \i Generate a C++ namespace \e namespace
55     \row
56     \i -nometaobject
57     \i Do not generate a .cpp file with the meta object information. 
58     The meta object is then generated in runtime.
59     \row
60     \i -getfile libid
61     \i Print the filename for the typelibrary \e libid to stdout
62     \row
63     \i -compat
64     \i Generate namespace with dynamicCall-compatible API
65     \row
66     \i -v
67     \i Print version information
68     \row
69     \i -h
70     \i Print help
71     \endtable
72
73     \c dumpcpp can be integrated into the \c qmake build system. In your .pro file, list the type 
74     libraries you want to use in the TYPELIBS variable:
75
76     \snippet examples/activeqt/qutlook/qutlook.pro 0
77
78     The generated namespace will declare all enumerations, as well as one QAxObject subclass 
79     for each \c coclass and \c interface declared in the type library. coclasses marked with 
80     the \c control attribute will be wrapped by a QAxWidget subclass.
81
82     Those classes that wrap creatable coclasses  (i.e. coclasses that are not marked 
83     as \c noncreatable) have a default constructor; this is typically a single class 
84     of type \c Application. 
85
86     \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 0
87
88     All other classes can only be created by passing an IDispatch interface pointer 
89     to the constructor; those classes should however not be created explicitly. 
90     Instead, use the appropriate API of already created objects.
91
92     \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 1
93
94     All coclass wrappers also have one constructors taking an interface wrapper class
95     for each interface implemented.
96
97     \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 2
98
99     You have to create coclasses to be able to connect to signals of the subobject.
100     Note that the constructor deletes the interface object, so the following will
101     cause a segmentation fault:
102
103     \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 3
104
105     If the return type is of a coclass or interface type declared in another type 
106     library you have to include the namespace header for that other type library 
107     before including the header for the namespace you want to use (both header have 
108     to be generated with this tool).
109
110     By default, methods and property returning subobjects will use the type as in 
111     the type library. The caller of the function is responsible for deleting or 
112     reparenting the object returned. If the \c -compat switch is set, properties 
113     and method returning a COM object have the return type \c IDispatch*, and 
114     the namespace will not declare wrapper classes for interfaces. 
115
116     In this case, create the correct wrapper class explicitly:
117
118     \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.cpp 4
119
120     You can of course use the IDispatch* returned directly, in which case you have to 
121     call \c Release() when finished with the interface.
122
123     All classes in the namespace are tagged with a macro that allows you to export
124     or import them from a DLL. To do that, declare the macro to expand to 
125     \c __declspec(dllimport/export) before including the header file.
126
127     To build the tool you must first build the QAxContainer library.
128     Then run your make tool in \c tools/dumpcpp.
129 */