doc/src/development/activeqt-dumpcpp.qdoc
changeset 0 1918ee327afb
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/development/activeqt-dumpcpp.qdoc	Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*! 
+    \page activeqt-dumpcpp.html
+    \title The dumpcpp Tool (ActiveQt)
+
+    \ingroup activeqt-tools
+
+    \keyword dumpcpp
+
+    The \c dumpcpp tool generates a C++ namespace for a type library.
+
+    To generate a C++ namespace for a type library, call \c dumpcpp with the following 
+    command line parameters:
+
+    \table
+    \header
+    \i Option
+    \i Result
+    \row
+    \i input
+    \i Generate documentation for \e input. \e input can specify a type library file or a type 
+    library ID, or a CLSID or ProgID for an object
+    \row
+    \i -o file
+    \i Writes the class declaration to \e {file}.h and meta object infomation to \e {file}.cpp
+    \row
+    \i -n namespace
+    \i Generate a C++ namespace \e namespace
+    \row
+    \i -nometaobject
+    \i Do not generate a .cpp file with the meta object information. 
+    The meta object is then generated in runtime.
+    \row
+    \i -getfile libid
+    \i Print the filename for the typelibrary \e libid to stdout
+    \row
+    \i -compat
+    \i Generate namespace with dynamicCall-compatible API
+    \row
+    \i -v
+    \i Print version information
+    \row
+    \i -h
+    \i Print help
+    \endtable
+
+    \c dumpcpp can be integrated into the \c qmake build system. In your .pro file, list the type 
+    libraries you want to use in the TYPELIBS variable:
+
+    \snippet examples/activeqt/qutlook/qutlook.pro 0
+
+    The generated namespace will declare all enumerations, as well as one QAxObject subclass 
+    for each \c coclass and \c interface declared in the type library. coclasses marked with 
+    the \c control attribute will be wrapped by a QAxWidget subclass.
+
+    Those classes that wrap creatable coclasses  (i.e. coclasses that are not marked 
+    as \c noncreatable) have a default constructor; this is typically a single class 
+    of type \c Application. 
+
+    \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 0
+
+    All other classes can only be created by passing an IDispatch interface pointer 
+    to the constructor; those classes should however not be created explicitly. 
+    Instead, use the appropriate API of already created objects.
+
+    \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 1
+
+    All coclass wrappers also have one constructors taking an interface wrapper class
+    for each interface implemented.
+
+    \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 2
+
+    You have to create coclasses to be able to connect to signals of the subobject.
+    Note that the constructor deletes the interface object, so the following will
+    cause a segmentation fault:
+
+    \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 3
+
+    If the return type is of a coclass or interface type declared in another type 
+    library you have to include the namespace header for that other type library 
+    before including the header for the namespace you want to use (both header have 
+    to be generated with this tool).
+
+    By default, methods and property returning subobjects will use the type as in 
+    the type library. The caller of the function is responsible for deleting or 
+    reparenting the object returned. If the \c -compat switch is set, properties 
+    and method returning a COM object have the return type \c IDispatch*, and 
+    the namespace will not declare wrapper classes for interfaces. 
+
+    In this case, create the correct wrapper class explicitly:
+
+    \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 4
+
+    You can of course use the IDispatch* returned directly, in which case you have to 
+    call \c Release() when finished with the interface.
+
+    All classes in the namespace are tagged with a macro that allows you to export
+    or import them from a DLL. To do that, declare the macro to expand to 
+    \c __declspec(dllimport/export) before including the header file.
+
+    To build the tool you must first build the QAxContainer library.
+    Then run your make tool in \c tools/dumpcpp.
+*/