/****************************************************************************

**

** 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-dotnet.html

    \title Dot Net Example (ActiveQt)

    The Dot Net example demonstrates how Qt objects can be used in a

    .NET environment, and how .NET objects can be used in a Qt

    environment.

    If you need to combine Qt and Win Forms widgets in the same

    application, you might want to use the higher-level

    \l{QtWinForms Solution} instead.

    Contents:

    \tableofcontents

    \section1 Qt vs. .NET

    Qt is a C++ library and is compiled into traditional, native

    binaries that make full use of the performance provided by the

    runtime environment.

    One of the key concepts of .NET is the idea of "intermediate language

    code" - the source code is compiled into a bytecode format, and at

    runtime, that bytecode is executed in a virtual machine - the \e

    {Common Language Runtime} (CLR).

    Another key concept is that of \e {managed code}. This is essentially

    intermediate language code written in such a way that the CLR can take

    care of the memory management, i.e. the CLR will do automatic garbage

    collection, so the application code does not need to explicitly free

    the memory for unused objects.

    The MS compilers for C# and VB.NET will only produce managed

    code. Such programs cannot directly call normal, native functions

    or classes. \footnote The .NET framework provides Platform Invocation

    Services - P/Invoke - that enable managed code to call native C (not

    C++) functions located in DLLs directly. The resulting application

    then becomes partially unmanaged.\endfootnote

    The MS C++ compiler for .NET on the other hand, can produce both

    normal and managed code. To write a C++ class that can be compiled

    into managed code, the developer must flag the class as managed using

    the \c __gc keyword, and restrict the code to only use the subset of

    C++ known as "Managed Extensions for C++", or MC++ for short. The

    advantage is that MC++ code can freely call and use normal C++

    functions and classes. And it also works the other way around: normal

    C++ code can call managed functions and use managed classes (e.g. the

    entire .NET framework class library), including managed functions and

    classes implemented in C# or VB.NET. This feature of mixing managed

    and normal C++ code immensely eases the interoperability with .NET,

    and is by Microsoft referred to as the "It Just Works" (IJW) feature.

    This document demonstrates two different ways of integrating normal

    C++ code (that uses Qt) with managed .NET code. First, the manual way

    is presented, which includes using a thin MC++ wrapper class around

    the normal Qt/C++ class. Then, the automated way is presented, which

    utilizes the ActiveQt framework as a generic bridge. The advantage of

    the first method is that it gives the application developer full

    control, while the second method requires less coding and relieves the

    developer of dealing with the conversion between managed and normal

    data objects.

    The impatient reader, who right away wants to see a QPushButton

    and a custom Qt widget (\l{activeqt/multiple}{QAxWidget2}) run in

    a .NET GUI application is referred to the example directory of

    ActiveQt. It contains the result of this walkthrough using both

    C# and VB.NET, created with Visual Studio .NET (not 2003).

    Load \c {examples/dotnet/walkthrough/csharp.csproj},

    \c {examples/dotnet/walkthrough/vb.vbproj}

    or \c {examples/dotnet/wrapper/wrapper.sln} into the IDE and run

    the solution.

    \bold{Remark:} You will notice that in the generated code the following line is

    commented out:

    \snippet doc/src/snippets/code/doc_src_examples_activeqt_dotnet.qdoc 0

    This line is regenerated without comment whenever you change the

    dialog, in which case you have to comment it out again to be able

    to run the project. This is a bug in the original version of

    Visual Studio.NET, and is fixed in the 2003 edition.

    \section1 Walkthrough: .NET interop with MC++ and IJW

    Normal C++ classes and functions can be used from managed .NET code by

    providing thin wrapper classes written in MC++. The wrapper class will

    take care of forwarding the calls to the normal C++ functions or

    methods, and converting parameter data as necessary. Since the wrapper

    class is a managed class, it can be used without further ado in any

    managed .NET application, whether written in C#, VB.NET, MC++ or other

    managed programming language.

    \snippet examples/activeqt/dotnet/wrapper/lib/worker.h 0

    The Qt class has nothing unusual for Qt users, and as even the Qt

    specialities like \c Q_PROPERTY, \c slots and \c signals are

    implemented with straight C++ they don't cause any trouble when

    compiling this class with any C++ compiler.

    \snippet examples/activeqt/dotnet/wrapper/lib/networker.h 0

    The .NET wrapper class uses keywords that are part of MC++ to indicate

    that the class is managed/garbage collected (\c {__gc}), and that \c

    StatusString should be accessible as a property in languages that

    support this concept (\c {__property}).  We also declare an event

    function \c statusStringChanged(String*) (\c {__event}), the

    equivalent of the respective signal in the Qt class.

    Before we can start implementing the wrapper class we need a way to

    convert Qt's datatypes (and potentionally your own) into .NET

    datatypes, e.g. \c QString objects need to be converted into objects

    of type \c {String*}.

    When operating on managed objects in normal C++ code, a little extra

    care must be taken because of the CLR's garbage collection. A normal

    pointer variable should not \footnote Indeed, the compiler will in

    many cases disallow it. \endfootnote be used to refer to a managed

    object. The reason is that the garbage collection can kick in at any

    time and move the object to another place on the heap, leaving you

    with an invalid pointer.

    However, two methods are provided that solves this problem easily. The

    first is to use a \e pinned pointer, i.e. declare the pointer variable

    with the \c __pin keyword. This guarantees that the object pointed to

    will not be moved by the garbage collector. It is recommended that

    this method not be used to keep a references to managed objects for a

    long time, since it will decrease the efficiency of the garbage

    collector. The second way is to use the \c gcroot smartpointer

    template type. This lets you create safe pointers to managed

    objects. E.g. a variable of type \c gcroot<String> will always point

    to the String object, even if it has been moved by the garbage

    collector, and it can be used just like a normal pointer.

    \snippet examples/activeqt/dotnet/wrapper/lib/tools.cpp 0

    \codeline

    \snippet examples/activeqt/dotnet/wrapper/lib/tools.cpp 1

    The convertor functions can then be used in the wrapper class

    implementation to call the functions in the native C++ class.

    \snippet examples/activeqt/dotnet/wrapper/lib/networker.cpp 0

    \codeline

    \snippet examples/activeqt/dotnet/wrapper/lib/networker.cpp 1

    The constructor and destructor simply create and destroy the Qt

    object wrapped using the C++ operators \c new and \c delete.

    \snippet examples/activeqt/dotnet/wrapper/lib/networker.cpp 2

    The netWorker class delegates calls from the .NET code to the native

    code. Although the transition between those two worlds implies a small

    performance hit for each function call, and for the type conversion,

    this should be negligible since we are anyway going to run within the

    CLR.

    \snippet examples/activeqt/dotnet/wrapper/lib/networker.cpp 3

    The property setter calls the native Qt class before firing the

    event using the \c __raise keyword.

    This wrapper class can now be used in .NET code, e.g. using C++, C#,

    Visual Basic or any other programming language available for .NET.

    \snippet examples/activeqt/dotnet/wrapper/main.cs 0

    \snippet examples/activeqt/dotnet/wrapper/main.cs 1

    \snippet examples/activeqt/dotnet/wrapper/main.cs 2

    \snippet examples/activeqt/dotnet/wrapper/main.cs 3

    \section1 Walkthrough: .NET/COM Interop with ActiveQt

    Fortunately .NET provides a generic wrapper for COM objects, the

    \e {Runtime Callable Wrapper} (RCW). This RCW is a proxy for the

    COM object and is generated by the CLR when a .NET Framework client

    activates a COM object. This provides a generic way to reuse COM

    objects in a .NET Framework project.

    Making a QObject class into a COM object is easily achieved with

    ActiveQt and demonstrated in the QAxServer examples (e.g., the

    \l{activeqt/simple}{Simple} example). The walkthrough will use

    the Qt classes implemented in those examples, so the first thing

    to do is to make sure that those  examples have been built

    correctly, e.g. by opening the

    \l{qaxserver-demo-multiple.html}{demonstration pages} in Internet

    Explorer to verify that the controls are functional.

    \section2 Starting a Project

    Start Visual Studio.NET, and create a new C# project for writing a

    Windows application. This will present you with an empty form in

    Visual Studio's dialog editor. You should see the toolbox, which

    presents you with a number of available controls and objects in

    different categories. If you right-click on the toolbox it allows

    you to add new tabs. We will add the tab "Qt".

    \section2 Importing Qt Widgets

    The category only has a pointer tool by default, and we have to add

    the Qt objects we want to use in our form. Right-click on the empty

    space, and select "Customize". This opens a dialog that has two

    tabs, "COM Components" and ".NET Framework Components". We used

    ActiveQt to wrap QWidgets into COM objects, so we select the "COM

    Components" page, and look for the classes we want to use, e.g.

    "QPushButton" and "QAxWidget2".

    When we select those widgets and close the dialog the two widgets

    will now be available from the toolbox as grey squares with their

    name next to it \footnote Icons could be added by modifying the

    way the controls register themselves. \endfootnote.

    \section2 Using Qt Widgets

    We can now add an instance of QAxWidget2 and a QPushButton to

    the form. Visual Studio will automatically generate the RCW for the

    object servers. The QAxWidget2 instance takes most of the upper

    part of the form, with the QPushButton in the lower right corner.

    In the property editor of Visual Studio we can modify the properties

    of our controls - QPushButton exposes the \c QWidget API and has many

    properties, while QAxWidget2 has only the Visual Studio standard

    properties in addition to its own property "lineWidth" in the

    "Miscellaneous" category. The objects are named "axQPushButton1" and

    "axQAxWidget21", and since especially the last name is a bit

    confusing we rename the objects to "resetButton" and "circleWidget".

    We can also change the Qt properties, e.g. set the "text" property

    of the \c resetButton to "Reset", and the "lineWidth" property of the

    \c circleWidget to 5. We can also put those objects into the layout

    system that Visual Studio's dialog editor provides, e.g. by setting

    the anchors of the \c circleWidget to "Left, Top, Right, Bottom", and

    the anchors of the \c resetButton to "Bottom, Right".

    Now we can compile and start the project, which will open a user

    interface with our two Qt widgets. If we can resize the dialog,

    the widgets will resize appropriately.

    \section2 Handling Qt Signals

    We will now implement event handlers for the widgets. Select the

    \c circleWidget and select the "Events" page in the property

    editor. The widget exposes events because the QAxWidget2 class has

    the "StockEvents" attribute set in its class definition. We implement

    the event handler \c circleClicked for the \c ClickEvent to increase

    the line width by one for every click:

    \snippet examples/activeqt/dotnet/walkthrough/Form1.cs 0

    In general we can implement a default event handler by double

    clicking on the widget in the form, but the default events for

    our widgets are right now not defined.

    We will also implement an event handler for the \c clicked signal

    emitted by QPushButton. Add the event handler \c resetLineWidth to

    the \c clicked event, and implement the generated function:

    \snippet examples/activeqt/dotnet/walkthrough/Form1.cs 1

    We reset the property to 1, and also call the \c setFocus() slot

    to simulate the user style on Windows, where a button grabs focus

    when you click it (so that you can click it again with the spacebar).

    If we now compile and run the project we can click on the circle

    widget to increase its line width, and press the reset button to

    set the line width back to 1.

    \section1 Summary

    Using ActiveQt as a universal interoperability bridge between the

    .NET world and the native world of Qt is very easy, and makes it

    often  unnecessary to implement a lot of handwritten wrapper classes.

    Instead, the QAxFactory implementation in the otherwise completely

    cross-platform Qt project provides the glue that .NET needs to to

    generate the RCW.

    If this is not sufficient we can implement our own wrapper classes

    thanks to the C++ extensions provided by Microsoft.

    \section2 Limitations

    All the limitations when using ActiveQt are implied when using this

    technique to interoperate with .NET, e.g. the datatypes we can use

    in the APIs can only be those supported by ActiveQt and COM. However,

    since this includes subclasses of QObject and QWidget we can wrap

    any of our datatypes into a QObject subclass to make its API

    available to .NET. This has the positive side effect that the same

    API is automatically available in

    \l{http://qt.nokia.com/products/qsa/}{QSA}, the cross platform

    scripting solution for Qt applications, and to COM clients in general.

    When using the "IJW" method, in priciple the only limitation is the

    time required to write the wrapper classes and data type conversion

    functions.

    \section2 Performance Considerations

    Every call from CLR bytecode to native code implies a small

    performance hit, and necessary type conversions introduce an

    additional delay with every layer that exists between the two

    frameworks. Consequently every approach to mix .NET and native

    code should try to minimize the communication necessary between

    the different worlds.

    As ActiveQt introduces three layers at once - the RCW, COM and finally

    ActiveQt itself - the performance penalty when using the generic

    Qt/ActiveQt/COM/RCW/.NET bridge is larger than when using a

    hand-crafted IJW-wrapper class. The execution speed however is still

    sufficient for connecting to and modifying interactive elements in a

    user interface, and as soon as the benefit of using Qt and C++ to

    implement and compile performance critical algorithms into native code

    kicks in, ActiveQt becomes a valid choice for making even non-visual

    parts of your application accessible to .NET.

    \sa {QtWinForms Solution}

*/