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 */